IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

LaTeX: make contents, topic, and sidebar separately customizable (#12704)

Browse Source 
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
This commit is contained in:
Jean-François B. 2024-08-19 20:43:47 +02:00 committed by GitHub
parent 48a8579786
commit 1c131dfffe
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
11 changed files with 411 additions and 177 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
CHANGES.rst
View File

@ -28,6 +28,9 @@ Features added
* #11328: Mention evaluation of templated content during production of static
output files.
* #12704: LaTeX: make :dudir:`contents <table-of-contents>`, :dudir:`topic`,
and :dudir:`sidebar` directives separately customizable for PDF output.
Patch by Jean-François B. and Bénédikt Tran.
* #12474: Support type-dependent search result highlighting via CSS.
Patch by Tim Hoffmann.
* #12652: LaTeX: Add :confval:`math_numsep` support to latex builder.
@ -56,6 +59,9 @@ Bugs fixed
Note, the priority of the transform has been changed from 200 to 622,
so that it now runs after the docutils ``Footnotes`` resolution transform.
Patch by Chris Sewell.
* #12778: LaTeX: let :ref:`'sphinxsetup' <latexsphinxsetup>`
``div.topic_box-shadow`` key if used with only one dimension set both
x-offset and y-offset as per documentation.
* #12587: Do not warn when potential ambiguity detected during Intersphinx
resolution occurs due to duplicate targets that differ case-insensitively.
Patch by James Addison.

214
doc/latex.rst
View File

@ -947,32 +947,24 @@ The color used in the above example is available from having passed the
Default: ``\fboxrule``
.. important::
Since 8.1.0 it is possible to style separately the :dudir:`topic`,
contents_, and :dudir:`sidebar` directives, and their defaults differ.
See :ref:`additionalcss`. The next three keys are kept as legacy
interface not distinguishing between the three directives.
``shadowsep``
The separation between contents and frame for contents_ and
:dudir:`topic` boxes.
See :ref:`additionalcss` for the alias ``div.topic_padding``.
Default: ``5pt``
This legacy option sets the padding (same in all directions) simultaneously
for the :dudir:`topic`, contents_, and :dudir:`sidebar` directives.
``shadowsize``
The width of the lateral "shadow" to the right and bottom.
See :ref:`additionalcss` for ``div.topic_box-shadow`` which allows to
configure separately the widths of the vertical and horizontal shadows.
Default: ``4pt``
.. versionchanged:: 6.1.2
Fixed a regression introduced at ``5.1.0`` which modified unintentionally
the width of topic boxes and worse had made usage of this key break PDF
builds.
This legacy option sets the shadow width simultaneously for the
:dudir:`topic`, contents_, and :dudir:`sidebar` directives.
``shadowrule``
The width of the frame around :dudir:`topic` boxes. See also
:ref:`additionalcss` for ``div.topic_border-width``.
Default: ``\fboxrule``
This legacy option sets the border-width (same on all sides) simultaneously
for the :dudir:`topic`, contents_, and :dudir:`sidebar` directives.
.. important::
@ -1155,6 +1147,13 @@ Additional CSS-like ``'sphinxsetup'`` keys
set the foreground and background colors for the title as well as the
LaTeX code for the icon.
.. versionadded:: 7.4.0
Customizability of the :rst:dir:`seealso` and
:rst:dir:`todo` directives.
.. versionadded:: 8.1.0
Separate customizability and new defaults for the
:dudir:`topic`, contents_, and :dudir:`sidebar` directives.
Perhaps in future these 5.1.0 (and 6.2.0) novel settings will be optionally
imported from some genuine CSS external file, but currently they have to be used
@ -1205,18 +1204,16 @@ which is then followed by an underscore, then the property name.
:header: Directive, Option prefix, LaTeX environment
:rst:dir:`code-block`, ``pre``, ``sphinxVerbatim``
:dudir:`topic`, ``div.topic``, ``sphinxShadowBox``
contents_, ``div.topic``, ``sphinxShadowBox``
:rst:dir:`literalinclude`, ``pre``, ``sphinxVerbatim``
:dudir:`topic`, ``div.topic``, ``sphinxtopic``
contents_, ``div.contents``, ``sphinxcontents``
:dudir:`sidebar`, ``div.sidebar``, ``sphinxsidebar``
:dudir:`note`, ``div.note``, ``sphinxnote``
:dudir:`warning`, ``div.warning``, ``sphinxwarning``
further admonition types ``<type>``, ``div.<type>``, ``sphinx<type>``
:rst:dir:`seealso`, ``div.seealso``, ``sphinxseealso``
:rst:dir:`todo`, ``div.todo``, ``sphinxtodo``
.. versionadded:: 7.4.0 Customizability of the :rst:dir:`seealso` and
:rst:dir:`todo` directives.
Here are now these options as well as their common defaults.
Replace below ``<prefix>`` by the actual prefix as explained above. Don't
forget the underscore separating the prefix from the property names.
@ -1231,16 +1228,19 @@ forget the underscore separating the prefix from the property names.
The default is that all those dimensions are equal. They are set to:
* ``0.4pt`` for :rst:dir:`code-block`,
* ``0.5pt`` for :dudir:`topic` or contents_ directive,
* ``0.5pt`` for :dudir:`topic` and contents_ directive,
* ``1pt`` for :dudir:`sidebar` directive,
* ``0.5pt`` for :dudir:`note` and other "light" admonitions,
* ``0.5pt`` for :rst:dir:`seealso` and :rst:dir:`todo` directives,
* ``1pt`` for :dudir:`warning` and other "strong" admonitions except
:dudir:`error` which uses ``1.25pt``.
.. versionchanged:: 7.4.0
Changed defaults for :dudir:`topic` and :dudir:`error`.
.. versionchanged:: 8.1.0
Distinct from :dudir:`topic` defaults for :dudir:`sidebar`.
- ``<prefix>_box-decoration-break`` can be set to either ``clone`` or
``slice`` and configures the behavior at page breaks.
It defaults to ``slice`` for :rst:dir:`code-block` (i.e. for ``<prefix>=pre``)
@ -1255,8 +1255,9 @@ forget the underscore separating the prefix from the property names.
The defaults:
* all four ``3pt`` for :rst:dir:`code-block`,
* ``10pt``, ``7pt``, ``12pt``, ``7pt`` for :dudir:`topic` or
contents_ directive,
* ``6pt``, ``7pt``, ``6pt``, ``7pt`` for :dudir:`topic`,
* ``10pt``, ``7pt``, ``12pt``, ``7pt`` for contents_,
* ``6pt``, ``5.5pt``, ``6pt``, ``5.5pt`` for :dudir:`sidebar`,
* ``6pt``, ``7pt``, ``6pt``, ``7pt`` for all "light" admonitions as well
as the :rst:dir:`seealso` and :rst:dir:`todo` directives.
* ``6pt``, ``6.5pt``, ``6pt``, ``6.5pt`` for the strong admonition types
@ -1270,6 +1271,9 @@ forget the underscore separating the prefix from the property names.
vertically across admonition types on same page in PDF. This is only a
property of defaults, not a constraint on possible user choices.
.. versionchanged:: 8.1.0
Separate defaults for :dudir:`topic`, contents_, and :dudir:`sidebar`.
- | ``<prefix>_border-top-left-radius``,
| ``<prefix>_border-top-right-radius``,
| ``<prefix>_border-bottom-right-radius``,
@ -1281,16 +1285,20 @@ forget the underscore separating the prefix from the property names.
The defaults:
* ``3pt`` for :rst:dir:`code-block` (since 6.0.0) and all corners,
* ``12pt`` for the bottom right corner of :dudir:`topic`, other corners are
straight,
* ``8pt`` for all corners of :dudir:`topic`,
* ``12pt`` for the bottom right corner of contents_, others use ``0pt``,
* ``12pt`` for the top-left and bottom-right corners for :dudir:`sidebar`,
``0pt`` for top-right and bottom-left.
* all radii set to ``5pt`` for :dudir:`note`, :dudir:`hint` and
:dudir:`tip`,
* ``0pt``, i.e. straight corners for all other directives.
.. versionchanged:: 7.4.0
:dudir:`topic` and :dudir:`note`\ -like
admonitions acquire (at least one) rounded corners.
:dudir:`topic` and :dudir:`note`\ -like admonitions acquire (at least one)
rounded corners.
.. versionchanged:: 8.1.0
Separate defaults for :dudir:`topic`, contents_, and :dudir:`sidebar`.
See a remark above about traps with spaces in LaTeX.
- ``<prefix>_box-shadow`` is special in so far as it may be:
@ -1300,11 +1308,16 @@ forget the underscore separating the prefix from the property names.
* or two dimensions (separated by a space),
* or two dimensions followed by the keyword ``inset``.
The x-offset and y-offset may be negative. The default is ``none``,
*except* for the :dudir:`topic` or contents_ directives, for which it is
``4pt 4pt``, i.e. the shadow has a width of ``4pt`` and extends to the right
and below the frame. The lateral shadow then extends into the page right
margin.
The x-offset and y-offset may be negative. A negative x-offset means
that the shadow is on the left. The shadow extends into the page margin,
whether the offset is positive or negative.
The default is ``none`` *except* for the contents_ directive which uses
``4pt 4pt``.
.. versionchanged:: 8.1.0
No shadow per default for :dudir:`topic` and :dudir:`sidebar`.
- | ``<prefix>_border-TeXcolor``,
| ``<prefix>_background-TeXcolor``,
| ``<prefix>_box-shadow-TeXcolor``,
@ -1321,14 +1334,14 @@ forget the underscore separating the prefix from the property names.
- ``{HTML}{F7F7F7}`` serves as background color to all.
- ``{HTML}{86989B}`` is border color of light admonitions (inclusive of
:rst:dir:`seealso` and :rst:dir:`todo`) as well as of :dudir:`topic` and
contents_ directives.
- ``{HTML}{940000}`` is border color or :dudir:`warning`-type admonitions,
:rst:dir:`seealso` and :rst:dir:`todo`) as well as of :dudir:`topic`,
contents_ and :dudir:`sidebar` directives.
- ``{HTML}{940000}`` is border color of :dudir:`warning`-type admonitions,
except :dudir:`error` which uses ``{HTML}{B40000}``.
The only directives displaying a shadow per default are :dudir:`topic` and
contents_ (handled identically at LaTeX level) and their shadow color is
``{HTML}{6C6C6C}``. For all others the default shadow color is black.
The only directives displaying a shadow per default are contents_ and
:dudir:`sidebar`. The shadow-color for the former is ``{HTML}{6C6C6C}``
and for the latter ``{HTML}{9EACAF}``.
The ``<prefix>_TeXcolor`` stands for the CSS property "color", i.e. it
influences the text color of the contents. As for the three other options,
@ -1347,19 +1360,16 @@ forget the underscore separating the prefix from the property names.
start of the contents; for admonitions, this happens after the heading which
reproduces the admonition type.
The next keys, for admonitions only, were all three added at 7.4.0. The
default colors are the ones applying to the current HTML rendering of Sphinx
own docs at https://www.sphinx-doc.org.
The next keys, for admonitions, :dudir:`topic`, contents_, and
:dudir:`sidebar`, were all three added at 7.4.0 (and 8.1.0 for the latter three).
- ``div.<type>_title-background-TeXcolor``: the background color for the title.
.. important::
The colored title-row is produced as a result of the Sphinx default
definitions for the various ``\sphinxstyle<type>title`` commands, see
:ref:`latex-macros`. Custom redefinitions of these commands are
possible, but to re-use the colors and the icon, it is needed to check in
Sphinx LaTeX source code how the default definitions are done.
definitions for the various ``\sphinxstyle<type>title`` commands, which
employ the ``\sphinxdotitlerow`` LaTeX command. See :ref:`latex-macros`.
- ``div.<type>_title-foreground-TeXcolor``: the color to be used for the icon
(it applies only to the icon, not to the title of the admonition).
@ -1436,24 +1446,19 @@ own docs at https://www.sphinx-doc.org.
.. _ellipse: https://ctan.org/pkg/ellipse
The following legacy behavior is currently not customizable:
The following legacy behavior applies:
- For :rst:dir:`code-block`, padding and border-width and shadow (if one adds
one) will go into the margin; the code lines remain at the same place
independently of the values of the padding and border-width, except for
being shifted vertically of course to not overwrite other text due to the
width of the border or external shadow.
- For :rst:dir:`code-block` or :rst:dir:`literalinclude`, padding and
border-width and shadow (if any) will go into the margin; the code
lines remain at the same place independently of the values of the padding
and border-width, except for being shifted vertically of course to not
overwrite other text due to the width of the border or external shadow.
- For :dudir:`topic` (and contents_) the shadow (if on right) goes into the
page margin, but the border and the extra padding are kept within the text
area. Same for admonitions.
- For the other directives, shadows extend horizontally into the page margins,
but the border and the extra padding are kept within the text area.
- The contents_ and :dudir:`topic` directives are governed by the same options
with ``div.topic`` prefix: the Sphinx LaTeX mark-up uses for both directives
the same ``sphinxShadowBox`` environment which has currently no additional
branching, contrarily to the ``sphinxadmonition`` environment which branches
according to the admonition directive name, e.g. either to ``sphinxnote``
or ``sphinxwarning`` etc...
- :rst:dir:`code-block` and :rst:dir:`literalinclude` use the same LaTeX
environment and commands and are not separately customizable.
LaTeX macros and environments
@ -1572,30 +1577,34 @@ Macros
``\sphinxstyleliteralintitle``; ``\sphinxcode{#1}``
``\sphinxstylecodecontinued``; ``{\footnotesize(#1)}}``
``\sphinxstylecodecontinues``; ``{\footnotesize(#1)}}``
``\sphinxstylenotetitle``; ``\sphinxdotitlerowwithicon{note}{#1}``
``\sphinxstylehinttitle``; ``\sphinxdotitlerowwithicon{hint}{#1}``
``\sphinxstyleimportanttitle``; *similar*
``\sphinxstyletiptitle``; *similar*
``\sphinxstylewarningtitle``; *similar*
``\sphinxstylecautiontitle``; *similar*
``\sphinxstyleattentiontitle``; *similar*
``\sphinxstyledangertitle``; *similar*
``\sphinxstyleerrortitle``; *similar*
``\sphinxstyleseealsotitle``; *similar*
``\sphinxstyletodotitle``; *similar*
``\sphinxstylenotetitle``; ``\sphinxdotitlerow{note}{#1}``
``\sphinxstylehinttitle``; ``\sphinxdotitlerow{hint}{#1}``
``\sphinxstyleimportanttitle``; ``\sphinxdotitlerow{important}{#1}``
``\sphinxstyletiptitle``; ``\sphinxdotitlerow{tip}{#1}``
``\sphinxstylewarningtitle``; ``\sphinxdotitlerow{warning}{#1}``
``\sphinxstylecautiontitle``; ``\sphinxdotitlerow{caution}{#1}``
``\sphinxstyleattentiontitle``; ``\sphinxdotitlerow{attention}{#1}``
``\sphinxstyledangertitle``; ``\sphinxdotitlerow{danger}{#1}``
``\sphinxstyleerrortitle``; ``\sphinxdotitlerow{error}{#1}``
``\sphinxstyleseealsotitle``; ``\sphinxdotitlerow{seealso}{#1}``
``\sphinxstyletodotitle``; ``\sphinxdotitlerow{todo}{#1}``
``\sphinxstyletopictitle``; ``\sphinxdotitlerow{topic}{#1}``
``\sphinxstylecontentstitle``; ``\sphinxdotitlerow{contents}{#1}``
``\sphinxstylesidebartitle``; ``\sphinxdotitlerow{sidebar}{#1}``
.. note::
To let this table fit on the page width in PDF output we have lied a bit
and the actual definition of ``\sphinxstylenotetitle`` is:
To let this table fit on the page width in PDF output we have lied a bit.
For instance, the actual definition of ``\sphinxstylenotetitle`` is:
.. code-block:: latex
\newcommand\sphinxstylenotetitle[1]%
{\sphinxdotitlerowwithicon{note}{\sphinxremovefinalcolon{#1}}}
{\sphinxdotitlerow{note}{\sphinxremovefinalcolon{#1}}}
The same remark applies to all other similar commands associated with
admonitions.
admonitions. The :dudir:`topic`, contents_, and :dudir:`sidebar` do not
use ``\sphinxremovefinalcolon`` as they don't need it.
.. versionadded:: 1.5
These macros were formerly hard-coded as non customizable ``\texttt``,
@ -1616,14 +1625,20 @@ Macros
directive, with a final colon. Wrap it as ``\sphinxremovefinalcolon{#1}``
if this final colon is to be removed.
.. versionadded:: 7.4.0 The ``\sphinxdotitlerowwithicon`` LaTeX command,
whose first argument is the admonition type, so that it can recover
the associated colours and icon for the title row, and the second
argument gets typeset after the icon.
.. versionadded:: 7.4.0
Added the ``\sphinxdotitlerowwithicon`` LaTeX command.
.. todo:: The fact that we must employ ``\sphinxremovefinalcolon`` is a
legacy artefact from old ill-designed Sphinx LaTeX writer,
which postfixes (still today) the title with a colon automatically.
.. versionchanged:: 8.1.0
``\sphinxdotitlerowwithicon`` now detects automatically if an icon is
associated or not with the rendered element used as first argument.
.. versionadded:: 8.1.0
Make ``\sphinxdotitlerow`` an alias to ``\sphinxdotitlerowwithicon``.
.. versionadded:: 8.1.0
Titles of :dudir:`topic`, contents_, and :dudir:`sidebar` directives are
also styled using ``\sphinxdotitlerow`` (they have no default icons
associated with them).
- ``\sphinxtableofcontents``: A wrapper (defined differently in
:file:`sphinxhowto.cls` and in :file:`sphinxmanual.cls`) of standard
@ -1799,17 +1814,19 @@ Environments
.. versionadded:: 6.1.0
.. versionchanged:: 6.2.0
Colon made part of the mark-up rather than being inserted by the
environment for coherence with how admonitions are handled generally.
- Environment for the :rst:dir:`todo` directive: ``sphinxtodo``.
It takes one argument which will be the localized string ``Todo``
followed with a colon.
It takes one argument, namely the localization of ``Todo``
(with a colon at the end; the default rendering will remove that
colon and put the localized string in its own colored title-row).
.. versionadded:: 7.4.0
- The contents_ directive (with ``:local:`` option) and the
:dudir:`topic` directive are implemented by environment ``sphinxShadowBox``.
- The :dudir:`topic`, contents_ and :dudir:`sidebar` directives
are associated with respectively ``sphinxtopic``, ``sphinxcontents``,
and ``sphinxsidebar`` environments.
.. versionadded:: 1.4.2
Former code refactored into an environment allowing page breaks.
@ -1817,7 +1834,12 @@ Environments
.. versionchanged:: 1.5
Options ``shadowsep``, ``shadowsize``, ``shadowrule``.
- The literal blocks (via ``::`` or :rst:dir:`code-block`), are
.. versionadded:: 8.1.0
Separate environments (all three wrappers around ``sphinxShadowBox``)
and separate customizability.
- The literal blocks (via ``::`` or :rst:dir:`code-block`), and literal
includes (:rst:dir:`literalinclude`) are
implemented using ``sphinxVerbatim`` environment which is a wrapper of
``Verbatim`` environment from package ``fancyvrb.sty``. It adds the handling
of the top caption and the wrapping of long lines, and a frame which allows

105
sphinx/texinputs/sphinx.sty
View File

@ -9,7 +9,7 @@
% by the Sphinx LaTeX writer.
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
\ProvidesPackage{sphinx}[2024/07/01 v7.4.0 Sphinx LaTeX package (sphinx-doc)]
\ProvidesPackage{sphinx}[2024/07/28 v8.1.0 Sphinx LaTeX package (sphinx-doc)]
% provides \ltx@ifundefined
% (many packages load ltxcmds: graphicx does for pdftex and lualatex but
@ -351,6 +351,11 @@
% is handled as an admonition with the same customizability. And the
% todo directive.
%
% 8.1.0: style separately topic, contents, and sidebar directives
% ---------------------------------------------------------------
%
% And use some title row also for them (but without icon, per default).
%
\def\spxstring@none{none}
\def\spxstring@clone{clone}
%
@ -398,6 +403,15 @@
% macro prefix option prefix legacy option init value
\spx@tempa{spx@pre@} {pre_} {verbatimborder} {0.4pt}
\spx@tempa{spx@topic@} {div.topic_} {shadowrule} {0.5pt}% mod. at 7.4.0
\spx@tempa{spx@contents@} {div.contents_} {shadowrule} {0.5pt}% 8.1.0
\spx@tempa{spx@sidebar@} {div.sidebar_} {shadowrule} {1pt}% 8.1.0
% let legacy shadowrule key set all topic/contents/sidebar border
% keys to the common value given by user to shadowrule
\def\KV@sphinx@shadowrule #1{%
\@nameuse{KV@sphinx@div.topic_border-width}{#1}%
\@nameuse{KV@sphinx@div.contents_border-width}{#1}%
\@nameuse{KV@sphinx@div.sidebar_border-width}{#1}%
}%
\spx@tempa{spx@note@} {div.note_} {noteborder} {0.5pt}
\spx@tempa{spx@hint@} {div.hint_} {hintborder} {0.5pt}
\spx@tempa{spx@important@}{div.important_}{importantborder}{0.5pt}
@ -445,9 +459,13 @@
% In order for perfect exact same vertical alignment of contents from all such
% directives, the value of horizontal border-width+padding is kept constant
% (equal to 7.5pt since 7.4.0).
% 8.1.0 styles separately topic, contents, and sidebar.
% #1 macro prefix #6 option prefix top right bottom left
\spx@tempa{spx@pre@} {pre_} {3pt}{3pt}{3pt}{3pt}
\spx@tempa{spx@topic@} {div.topic_} {10pt}{7pt}{12pt}{7pt}
\spx@tempa{spx@topic@} {div.topic_} {6pt}{7pt}{6pt}{7pt}% mod. at 8.1.0
% contents styling inherits at 8.1.0 the former 7.4.0 topic defaults
\spx@tempa{spx@contents@} {div.contents_} {10pt}{7pt}{12pt}{7pt}% 8.1.0
\spx@tempa{spx@sidebar@} {div.sidebar_} {6pt}{6.5pt}{6pt}{6.5pt}% 8.1.0
% 7.4.0 drops legacy settings which linked strangely padding with border width
\spx@tempa{spx@note@} {div.note_} {6pt}{7pt}{6pt}{7pt}
\spx@tempa{spx@hint@} {div.hint_} {6pt}{7pt}{6pt}{7pt}
@ -463,8 +481,13 @@
\spx@tempa{spx@box@} {box_} {3pt}{3pt}{3pt}{3pt}
% define legacy verbatimsep key as alias of pre_padding key
\expandafter\let\expandafter\KV@sphinx@verbatimsep\csname KV@sphinx@pre_padding\endcsname
% define legacy shadowsep key as alias of div.topic_padding key
\expandafter\let\expandafter\KV@sphinx@shadowsep\csname KV@sphinx@div.topic_padding\endcsname
% let legacy shadowsep key set all topic/contents/sidebar padding
% keys to the common value given by user to shadosep
\def\KV@sphinx@shadowsep #1{%
\@nameuse{KV@sphinx@div.topic_padding}{#1}%
\@nameuse{KV@sphinx@div.contents_padding}{#1}%
\@nameuse{KV@sphinx@div.sidebar_padding}{#1}%
}%
% Corner radii keys
%
@ -492,9 +515,16 @@
% - the 3pt is used (which is normal value of \fboxsep).
% - some admonitions use rounded corners as well.
% - topic boxed have only their bottom right corner rounded.
% At 8.1.0 topic, contents and sidebar separately styled.
% macro prefix option prefix tl tr br bl
\spx@tempa{spx@pre@} {pre_} {3pt}{3pt}{3pt}{3pt}
\spx@tempa{spx@topic@} {div.topic_} \z@ \z@ {12pt} \z@
% use four rounded corners (and no shadow) for topic at 8.1.0
\spx@tempa{spx@topic@} {div.topic_} {8pt}{8pt}{8pt}{8pt}
% contents inherits at 8.1.0 the 7.4.0 former styling of topic
\spx@tempa{spx@contents@} {div.contents_} \z@ \z@ {12pt} \z@
% make sidebard distinctive as we can't really safely implement
% it with text flowing around it, but rather as a full width block
\spx@tempa{spx@sidebar@} {div.sidebar_} {12pt}\z@ {12pt} \z@
\spx@tempa{spx@note@} {div.note_} {5pt}{5pt}{5pt}{5pt}
\spx@tempa{spx@hint@} {div.hint_} {5pt}{5pt}{5pt}{5pt}
\spx@tempa{spx@important@}{div.important_} \z@\z@\z@\z@
@ -523,6 +553,8 @@
% macro prefix
\spx@tempa{spx@pre@}
\spx@tempa{spx@topic@}
\spx@tempa{spx@contents@}% 8.1.0
\spx@tempa{spx@sidebar@}% 8.1.0
\spx@tempa{spx@note@}
\spx@tempa{spx@hint@}
\spx@tempa{spx@important@}
@ -556,13 +588,10 @@
% used here. Since 6.2.0, expansion is delayed to time of use as for
% the other dimensions handled above. This is synched with an added
% encapsulation in \dimexpr...\relax by the "setup" from
% sphinxpackageboxes.sty. An induced regression had to be fixed in
% the sphinxShadowBox environment as it was using in an \ifdim the
% \spx@topic@shadow@yoffset macro, now holding by default 4pt+\z@
% rather than an already digested 262144sp. The +\z@ is in case ##2
% is empty.
% sphinxpackageboxes.sty.
\else #1%
\def#6{##1}\def#7{##2+\z@}%
\def#6{##1}%
\if\relax\detokenize{##2}\relax\let#7#6\else\def#7{##2}\fi
\if\relax\detokenize{##3}\relax#4\else#3\fi
\fi
}%
@ -570,8 +599,12 @@
}
\spx@tempa{spx@pre@} {pre_}
\spx@tempa{spx@topic@} {div.topic_}
% This corresponds to the legacy parameters of ShadowBox
\spx@topic@shadow@setter 4pt 4pt {} \@nnil
\spx@tempa{spx@contents@} {div.contents_}
\spx@tempa{spx@sidebar@} {div.sidebar_}
% This corresponds to the legacy parameters for topic/contents/sidebar,
% but they are now only kept for contents
\spx@contents@shadow@setter 4pt 4pt {} \@nnil
% topic and sidebar default to no shadow
\spx@tempa{spx@note@} {div.note_}
\spx@tempa{spx@hint@} {div.hint_}
\spx@tempa{spx@important@}{div.important_}
@ -585,18 +618,28 @@
\spx@tempa{spx@error@} {div.error_}
\spx@tempa{spx@box@} {box_}
% Support for legacy shadowsize (topic/contents)
% Support for legacy shadowsize (topic/contents/sidebar)
% This definition was broken due to a typo at 5.1.0 and got fixed at 6.1.2
% MEMO: at 6.2.0 this no longer does \number\dimexpr in an \edef. Reason is to
% keep in sync with div.topic_box-shadow handling of xoffset and yoffset.
\define@key{sphinx}{shadowsize}{%
\def\spx@topic@shadow@xoffset{#1}%
\let\spx@topic@shadow@yoffset\spx@topic@shadow@xoffset
\let\spx@contents@shadow@xoffset\spx@topic@shadow@xoffset
\let\spx@sidebar@shadow@xoffset \spx@topic@shadow@xoffset
\let\spx@topic@shadow@yoffset \spx@topic@shadow@xoffset
\let\spx@contents@shadow@yoffset\spx@topic@shadow@xoffset
\let\spx@sidebar@shadow@yoffset \spx@topic@shadow@xoffset
\ifdim\dimexpr\spx@topic@shadow@xoffset=\z@
\spx@topic@withshadowfalse
\spx@contents@withshadowfalse
\spx@sidebar@withshadowfalse
\else
\spx@topic@withshadowtrue
\spx@topic@insetshadowfalse
\spx@contents@withshadowtrue
\spx@contents@insetshadowfalse
\spx@sidebar@withshadowtrue
\spx@sidebar@insetshadowfalse
\fi
}%
@ -639,6 +682,8 @@
% macro prefix
\spx@tempa{spx@pre@}
\spx@tempa{spx@topic@}
\spx@tempa{spx@contents@}
\spx@tempa{spx@sidebar@}
\spx@tempa{spx@note@}
\spx@tempa{spx@hint@}
\spx@tempa{spx@important@}
@ -691,7 +736,11 @@
\csname KV@sphinx@pre_background-TeXcolor\endcsname
% (6.2.0 modified some internal namings for the colors of topic boxes)
% macro prefix option prefix color name prefix
\spx@tempa{spx@topic@} {div.topic_} {sphinxtopic}% (no legacy interface)
% There was no legacy interface for topic/contents/sidebar
% 8.1.0 allows separate styling for topic/contents/sidebar
\spx@tempa{spx@topic@} {div.topic_} {sphinxtopic}
\spx@tempa{spx@contents@} {div.contents_} {sphinxcontents}
\spx@tempa{spx@sidebar@} {div.sidebar_} {sphinxsidebar}
\spx@tempa{spx@note@} {div.note_} {sphinxnote}
\spx@tempa{spx@hint@} {div.hint_} {sphinxhint}
\spx@tempa{spx@important@}{div.important_} {sphinximportant}
@ -744,9 +793,18 @@
% At 7.4.0, let topic/contents boxes acquire background and border colours
% and give the shadow some colour other than black
\setkeys{sphinx}{div.topic_border-TeXcolor=sphinx-admonition-bordercolor,
% 8.1.0 styles separately topic/contents/sidebar
% topic has no shadow but we keep 7.4.0 color in case it gets needed
\setkeys{sphinx}{%
div.topic_border-TeXcolor=sphinx-admonition-bordercolor,
div.topic_background-TeXcolor=sphinx-admonition-bgcolor,
div.topic_box-shadow-TeXcolor={RGB}{108,108,108},
div.contents_border-TeXcolor=sphinx-admonition-bordercolor,
div.contents_background-TeXcolor=sphinx-admonition-bgcolor,
div.contents_box-shadow-TeXcolor={RGB}{108,108,108},
div.sidebar_border-TeXcolor=sphinx-admonition-bordercolor,
div.sidebar_background-TeXcolor=sphinx-admonition-bgcolor,
div.sidebar_box-shadow-TeXcolor=sphinx-admonition-bordercolor!80,% #9eacaf
}
@ -800,8 +858,14 @@
div.error_title-background-TeXcolor=sphinx-error-title-bgcolor,
div.error_title-foreground-TeXcolor=sphinx-error-title-fgcolor,
%
% TODO: implement todo (sic)
%
% 8.1.0 add title rows, but will not use icons per default, so
% the fgcolor setting will be used only if user uses title-icon key
div.topic_title-background-TeXcolor=sphinx-admonition-title-bgcolor,
div.topic_title-foreground-TeXcolor=sphinx-admonition-title-fgcolor,
div.contents_title-background-TeXcolor=sphinx-admonition-title-bgcolor,
div.contents_title-foreground-TeXcolor=sphinx-admonition-title-fgcolor,
div.sidebar_title-background-TeXcolor=sphinx-note-title-bgcolor,
div.sidebar_title-foreground-TeXcolor=sphinx-note-title-fgcolor,
}
% 7.4.0 Support for icons in admonition titles
@ -882,6 +946,9 @@
div.attention_title-icon = \spx@faIcon{exclamation-triangle},
div.danger_title-icon = \spx@faIcon{radiation},
div.error_title-icon = \spx@faIcon{times-circle},
% MEMO: the new at 8.1.0 defaults for contents/topic/sidebar directives
% use no icons, they use \sphinxdotitlerow which detects automatically
% whether title-icon key has been set or not.
}
\newif\ifspx@opt@box@addstrut

82
sphinx/texinputs/sphinxlatexadmonitions.sty
View File

@ -1,15 +1,12 @@
%% NOTICES AND ADMONITIONS
%
% change this info string if making any custom modification
\ProvidesPackage{sphinxlatexadmonitions}[2024/07/01 v7.4.0 admonitions]
\ProvidesPackage{sphinxlatexadmonitions}[2024/07/28 v8.1.0 admonitions]
% Provides support for this output mark-up from Sphinx latex writer:
%
% - sphinxseealso environment added at 6.1.0.
%
% At 7.4.0 it too now uses sphinxheavybox, and has the same associated
% sphinxsetup CSS keys as admonitions do.
%
% - sphinxtodo environment added at 7.4.0.
%
% - sphinxadmonition (environment)
@ -19,16 +16,21 @@
% sphinxheavybox since 6.2.0),
% - warning, caution, attention, danger, error to use sphinxheavybox.
%
% At 7.4.0 all admonitions use sphinxheavybox.
% Since 7.4.0 all admonitions use sphinxheavybox.
%
% - All environments sphinxnote, sphinxwarning, etc... can be redefined as
% will by user. Thay have a single parameter #1 which is the title.
%
% - The default sphinxnote, sphinxwarning, etc... use associated
% one-argument macros \sphinxstylenotetitle, \sphinxstylewarningtitle, etc
% which can be redefined. Their default is to use \sphinxdotitlerowwithicon
% to typeset the title in a coloured header row at top of the
% admonition. (new with 7.4.0)
% - Also redefinable by user are the one-argument commands
% * \sphinxstylenotetitle,
% * \sphinxstylewarningtitle,
% * etc.... one for each admonition type (also seealso and todo).
%
% - At 7.4.0, all commands of previous item use \sphinxdotitlerow.
% (the 7.4.0 name, still usable, was \sphinxdotitlerowwithicon; the 8.1.0
% version is also used for topic, contents and sidebar directives, see
% sphinxlatexshadowbox.sty, and handles both "with icon" and "without
% icon" situations).
%
% The sphinxlightbox environment is kept for backward compatiblity, for user
% custom code which used it via custom definitions done in preamble or via
@ -42,20 +44,21 @@
% (the 7.4.0 redefined \sphinxstylenotetitle will not work in sphinxlightbox,
% so \sphinxstrong{#1}<space> which was its former default is used above).
%
% Requires:
\RequirePackage{sphinxpackageboxes}
% 7.4.0 removes unneeded \spx@boxes@border
\RequirePackage{framed}% used by sphinxheavybox
%
% Dependencies (they do not need to be defined at time of loading):
%
% - of course the various colour and dimension options handled via sphinx.sty
%
% - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty
% - \savenotes/\spewnotes from sphinxpackagefootnote.sty
% - \ifspx@inframed defined in sphinx.sty
% - \spx@boxes@fcolorbox@setup from sphinxpackageboxes.sty
%
\RequirePackage{framed}
% Those are required either before or after by sphinx.sty anyhow, but for
% clarity we list them here:
\RequirePackage{sphinxlatexgraphics}
\RequirePackage{sphinxpackagefootnote}
\RequirePackage{sphinxpackageboxes}
%
% - \savenotes/\spewnotes from sphinxpackagefootnote (for sphinxheavybox)
% Provides: (also in sphinxlatexliterals.sty)
% Only needed here by legacy (deprecated) sphinxlightbox environment.
\providecommand*\sphinxvspacefixafterfrenchlists{%
@ -300,10 +303,15 @@
% workaround some LaTeX "feature" of \end command (i.e. can't use "sphinx#1" here)
{\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp}
% TODO: allow these next three settings to be customized individually.
% This can however already be done at user level by \renewcommand
% inside renew'ed environments sphinxnote, sphinxhint etc...
\newcommand\sphinxtitlerowtoppadding{5pt}
\newcommand\sphinxtitlerowbottompadding{3pt}
\newcommand\sphinxtitlerowaftericonspacecmd{\hskip0.5em\relax}
\newcommand\sphinxdotitlerowwithicon[2]{% #1=type, #2=heading (without final colon)
% 7.4.0 used this longer name:
\newcommand\sphinxdotitlerowwithicon{\sphinxdotitlerow}
\newcommand\sphinxdotitlerow[2]{% #1=type, #2=heading (without final colon)
\begingroup
\kern-\spx@boxes@padding@top
\parskip\z@skip % the \parskip business is a workaround to a vertical
@ -325,7 +333,12 @@
\spx@boxes@withshadowfalse
\sphinxcolorlet{spx@boxes@backgroundcolor}{sphinx#1TtlBgColor}%
\spx@boxes@fcolorbox{%
\makebox[\linewidth][l]{%
\parbox[t]{\linewidth}{% 7.4.0 used \makebox, but wrapping of long titles
% is needed for generic admonition or topic box.
\sphinxAtStartPar
% 8.1.0 auto-drops extra space if no icon
\sbox\z@{\@nameuse{sphinx#1TtlIcon}}%
\ifdim\wd\z@>\z@
\textcolor{sphinx#1TtlFgColor}{%
\@nameuse{sphinx#1TtlIcon}%
% This macro is located here and not after the closing brace
@ -333,8 +346,11 @@
% in case fontawesome5 package not found.
\sphinxtitlerowaftericonspacecmd
}%
\fi
\sphinxstrong{#2}%
\strut}%
\strut
\par
}%
}%
\kern-\spx@boxes@padding@right
\par
@ -347,17 +363,17 @@
% \sphinxremovefinalcolon{#1} will typeset #1 without the colon.
% Legacy definitions (done in sphinxlatexstyletext.sty) were all using
% a boring plain \sphinxstrong{#1}, now we use a coloured title row.
\newcommand\sphinxstylenotetitle [1]{\sphinxdotitlerowwithicon{note}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstylehinttitle [1]{\sphinxdotitlerowwithicon{hint}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyleimportanttitle[1]{\sphinxdotitlerowwithicon{important}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyletiptitle [1]{\sphinxdotitlerowwithicon{tip}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstylewarningtitle [1]{\sphinxdotitlerowwithicon{warning}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstylecautiontitle [1]{\sphinxdotitlerowwithicon{caution}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyleattentiontitle[1]{\sphinxdotitlerowwithicon{attention}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyledangertitle [1]{\sphinxdotitlerowwithicon{danger}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyleerrortitle [1]{\sphinxdotitlerowwithicon{error}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyleseealsotitle [1]{\sphinxdotitlerowwithicon{seealso}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyletodotitle [1]{\sphinxdotitlerowwithicon{todo}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstylenotetitle [1]{\sphinxdotitlerow{note}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstylehinttitle [1]{\sphinxdotitlerow{hint}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyleimportanttitle[1]{\sphinxdotitlerow{important}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyletiptitle [1]{\sphinxdotitlerow{tip}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstylewarningtitle [1]{\sphinxdotitlerow{warning}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstylecautiontitle [1]{\sphinxdotitlerow{caution}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyleattentiontitle[1]{\sphinxdotitlerow{attention}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyledangertitle [1]{\sphinxdotitlerow{danger}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyleerrortitle [1]{\sphinxdotitlerow{error}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyleseealsotitle [1]{\sphinxdotitlerow{seealso}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyletodotitle [1]{\sphinxdotitlerow{todo}{\sphinxremovefinalcolon{#1}}}
%
% A utility to remove a final colon. Removing last token is not easy in
% LaTeX, and there are additional complications:

82
sphinx/texinputs/sphinxlatexshadowbox.sty
View File

@ -1,21 +1,37 @@
%% TOPIC AND CONTENTS BOXES
%
% change this info string if making any custom modification
\ProvidesPackage{sphinxlatexshadowbox}[2023/03/19 sphinxShadowBox]
\ProvidesPackage{sphinxlatexshadowbox}[2024/07/28 v8.1.0 sphinxShadowBox]
% Provides support for this output mark-up from Sphinx latex writer:
%
% - sphinxShadowBox (environment)
% - Environments: sphinxtopic, sphinxcontents, and sphinxsidebar.
%
% These wrappers replace at 8.1.0 former direct use of sphinxShadowBox
% environment which did not allow separate styling.
%
% - Commands: \sphinxstyletopictitle, \sphinxstylecontentstitle, and
% \sphinxstylesidebartitle.
%
% At 8.1.0 they default to use \sphinxdotitlerow whose definiion is done in
% sphinxlatexadmonitions.sty. There is also \sphinxstylesidebarsubtitle
% which does not use \sphinxdotitlerow.
%
% Dependencies (they do not need to be defined at time of loading):
%
% - of course the various colour and dimension options handled via sphinx.sty
% - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty
% - \savenotes/\spewnotes from sphinxpackagefootnote
% - \savenotes/\spewnotes from sphinxpackagefootnote.sty
% - \ifspx@inframed defined in sphinx.sty
% - \sphinxdotitlerow from sphinxlatexadmonitions.sty
% - \spx@boxes@fcolorbox@setup from sphinxpackageboxes.sty
%
% Requires:
\RequirePackage{framed}
% Those are required either before or after by sphinx.sty anyhow, but for
% clarity we list them here:
\RequirePackage{sphinxlatexgraphics}
\RequirePackage{sphinxpackagefootnote}
\RequirePackage{sphinxlatexadmonitions}
\RequirePackage{sphinxpackageboxes}
% At 5.1.0 the code formerly here in a definition of \spx@ShadowFBox has been
@ -45,9 +61,28 @@
% in contrast with the framing used for literal blocks, also based, but in a
% more sophisticated way on usage of \MakeFramed/\endMakeFramed, and
% adjusting to current text indentation.
\newenvironment{sphinxShadowBox}
%
% At 8.1.0, sphinxShadowBox takes an optional argument #1 and uses it as
% \spx@boxes@fcolorbox@setup{#1} rather than \spx@boxes@fcolorbox@setup{topic}.
% Some hesitation whether to move this line to newly added sphinxtopic,
% sphinxcontents and sphinxsidebar environmments. But anyhow the environment
% also requires later knowing a few more things: sphinx<type>TextColor and
% spx@<type>@texextras.
%
% The #1 defaulting to topic must be such that all parameters expected by
% \spx@boxes@fcolorbox@setup actually do exist, see CSS options in sphinx.sty
% which is what defines them for contents, topic, and sidebar.
%
% Fortunately the #1 is not needed in \end{sphinxShadowBox} so we don't have
% to work around a LaTeX conception bug that such #1 can not be used as is in
% the definition of the \end part of an environment.
%
% MEMO: the "shadow" is not really drawn directly by this environment but
% indirectly via the configuration which is passed over to \spx@boxes@fcolorbox,
% which is the macro creating frame and (perhaps but not necessarily) a shadow.
\newenvironment{sphinxShadowBox}[1][topic]%
{%
\spx@boxes@fcolorbox@setup{topic}%
\spx@boxes@fcolorbox@setup{#1}%
% we will use the dimen registers from sphinxpackageboxes.sty which now hold
% the values from options related to topic/contents
% MEMO: \spx@boxes@fcolorbox creates an \hbox but does not quit vertical
@ -56,7 +91,7 @@
\def\FrameCommand {\spx@boxes@fcolorbox}%
% 6.2.0 adds support for div.topic_box-decoration-break=slice.
% (it is yet undecided if slice style should inhibit a bottom shadow)
\ifspx@topic@border@open
\@nameuse{ifspx@#1@border@open}%
\def\FirstFrameCommand
{\spx@boxes@fcolorbox@setup@openbottom\FrameCommand}%
\def\MidFrameCommand
@ -97,10 +132,10 @@
\@setminipage
}%
\color@begingroup % workaround upstream framed.sty bug
\ifspx@topic@withtextcolor
\color{sphinxtopicTextColor}%
\@nameuse{ifspx@#1@withtextcolor}%
\color{sphinx#1TextColor}%
\fi
\spx@topic@TeXextras
\@nameuse{spx@#1@TeXextras}%
}%
{% insert the "endminipage" code
\par\unskip
@ -113,4 +148,31 @@
\spewnotes
}
% 8.1.0
\newenvironment{sphinxtopic}
{\begin{sphinxShadowBox}[topic]}{\end{sphinxShadowBox}}
\newenvironment{sphinxcontents}
{\begin{sphinxShadowBox}[contents]}{\end{sphinxShadowBox}}
% Arguably sphinxsidebar should rather use a wrapfig or similar environment
% but this is so dysfunctional in LaTeX (except for self-written documents)
% so we prefer to not venture into such a potential quagmire and keep the
% legacy rendering using a full width display.
\newenvironment{sphinxsidebar}
{\begin{sphinxShadowBox}[sidebar]}{\end{sphinxShadowBox}}
% TODO: decide if this should be in sphinxlatexstyletext.sty rather
%
% 8.1.0 styles topic/contents/sidebar with a title row, too.
% Prior to 8.1.0, definitions use \protected\def but there does not seem
% to be any reason so back to \newcommand.
\newcommand*\sphinxstyletopictitle[1]{\sphinxdotitlerow{topic}{#1}}
\newcommand*\sphinxstylecontentstitle[1]{\sphinxdotitlerow{contents}{#1}}
\newcommand*\sphinxstylesidebartitle[1]{\sphinxdotitlerow{sidebar}{#1}}
% No default color background for subtitle. The contents next are injected by
% LaTeX writer after a blank line in source hence will start a new paragrpah.
% The \sphinxAtStartPar here is only for coherence with other text paragraphs,
% but does not have serious necessity (its general role is to allow hyphenation
% for first word in narrow table cells).
\newcommand*\sphinxstylesidebarsubtitle[1]{\sphinxAtStartPar\textbf{#1}}
\endinput

6
sphinx/texinputs/sphinxlatexstyletext.sty
View File

@ -1,9 +1,10 @@
%% TEXT STYLING
%
% change this info string if making any custom modification
\ProvidesPackage{sphinxlatexstyletext}[2024/07/01 v7.4.0 text styling]
\ProvidesPackage{sphinxlatexstyletext}[2024/07/28 v8.1.0 text styling]
% 7.4.0 has moved all that is related to admonitions to sphinxlatexadmonitions.sty
% 8.1.0 has moved topic/contents/sidebar to sphinxlatexshadowbox.sty
% Most everything left here consists of macros which are part of the latex markup
% produced by the Sphinx LaTeX writer.
@ -39,10 +40,7 @@
{{\Large\sffamily#1}\nopagebreak\vspace{1mm}}
\def\sphinxstyleindexlettergroupDefault #1%
{{\Large\sffamily\sphinxnonalphabeticalgroupname}\nopagebreak\vspace{1mm}}
\protected\def\sphinxstyletopictitle #1{\textbf{#1}\par\medskip}
\let\sphinxstylesidebartitle\sphinxstyletopictitle
\protected\def\sphinxstyleothertitle #1{\textbf{#1}}
\protected\def\sphinxstylesidebarsubtitle #1{~\\\textbf{#1} \smallskip}
% \text.. commands do not allow multiple paragraphs
% attention, this one is not self-delimiting
\protected\def\sphinxstyletheadfamily {\sffamily}

22
sphinx/writers/latex.py
View File

@ -585,13 +585,22 @@ class LaTeXTranslator(SphinxTranslator):
self.body.append('}')
def visit_topic(self, node: Element) -> None:
self.in_minipage = 1
self.body.append(CR + r'\begin{sphinxShadowBox}' + CR)
self.in_minipage += 1
if 'contents' in node.get('classes', []):
self.body.append(CR + r'\begin{sphinxcontents}' + CR)
self.context.append(r'\end{sphinxcontents}' + CR)
else:
self.body.append(CR + r'\begin{sphinxtopic}' + CR)
self.context.append(r'\end{sphinxtopic}' + CR)
def depart_topic(self, node: Element) -> None:
self.in_minipage = 0
self.body.append(r'\end{sphinxShadowBox}' + CR)
visit_sidebar = visit_topic
self.in_minipage -= 1
self.body.append(self.context.pop())
def visit_sidebar(self, node: Element) -> None:
self.in_minipage += 1
self.body.append(CR + r'\begin{sphinxsidebar}' + CR)
self.context.append(r'\end{sphinxsidebar}' + CR)
depart_sidebar = depart_topic
def visit_glossary(self, node: Element) -> None:
@ -654,6 +663,9 @@ class LaTeXTranslator(SphinxTranslator):
self.body.append(fr'\{self.sectionnames[-1]}{short}{{')
self.context.append('}' + CR + self.hypertarget_to(node.parent))
elif isinstance(parent, nodes.topic):
if 'contents' in parent.get('classes', []):
self.body.append(r'\sphinxstylecontentstitle{')
else:
self.body.append(r'\sphinxstyletopictitle{')
self.context.append('}' + CR)
elif isinstance(parent, nodes.sidebar):

0
tests/roots/test-latex-contents-topic-sidebar/conf.py Normal file
View File

19
tests/roots/test-latex-contents-topic-sidebar/index.rst Normal file
View File

@ -0,0 +1,19 @@
test-contents-et-al
===================
.. contents::
test-topic
----------
.. topic:: Title of topic
text of topic
test-sidebar
------------
.. sidebar:: Title of sidebar
:subtitle: sub-title
text of sidebar

13
tests/roots/test-root/conf.py
View File

@ -70,10 +70,15 @@ latex_elements = {
%
shadowrule=1pt,
shadowsep=10pt,
shadowsize=10pt,
div.topic_border-width=2pt,% alias to shadowrule
div.topic_padding=6pt,% alias to shadowsep
div.topic_box-shadow=5pt,% overrides/alias shadowsize
shadowsize=-10pt,
div.topic_border-width=2pt,
div.topic_padding=6pt,
div.topic_box-shadow=5pt,
div.contents_border-width=3pt,
div.contents_padding=10pt,
div.contents_box-shadow=none,
div.sidebar_border-width=0pt,
div.sidebar_border-radius=0pt,
%
noteBorderColor={RGB}{204,204,204},
hintBorderColor={RGB}{204,204,204},

27
tests/test_builders/test_build_latex.py
View File

@ -2275,3 +2275,30 @@ def test_latex_rubric(app):
content = (app.outdir / 'test.tex').read_text(encoding='utf8')
assert r'\subsubsection*{This is a rubric}' in content
assert r'\subsection*{A rubric with a heading level 2}' in content
@pytest.mark.sphinx('latex', testroot='latex-contents-topic-sidebar')
def test_latex_contents_topic_sidebar(app):
app.build()
result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8')
assert '\\begin{sphinxcontents}\n\\sphinxstylecontentstitle{Contents}\n' in result
assert (
'\\begin{sphinxtopic}\n'
'\\sphinxstyletopictitle{Title of topic}\n'
'\n'
'\\sphinxAtStartPar\n'
'text of topic\n'
'\\end{sphinxtopic}\n'
) in result
assert (
'\\begin{sphinxsidebar}\n'
'\\sphinxstylesidebartitle{Title of sidebar}\n'
'\\sphinxstylesidebarsubtitle{sub\\sphinxhyphen{}title}\n'
'\n'
'\\sphinxAtStartPar\n'
'text of sidebar\n'
'\\end{sphinxsidebar}\n'
) in result