diff --git a/CHANGES.rst b/CHANGES.rst index 44fcb99403c..3f0ce6e7ba0 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -28,6 +28,9 @@ Features added * #11328: Mention evaluation of templated content during production of static output files. +* #12704: LaTeX: make :dudir:`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' ` + ``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. diff --git a/doc/latex.rst b/doc/latex.rst index 2e0baef1f38..5c9c503565b 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -947,32 +947,24 @@ The color used in the above example is available from having passed the Default: ``\fboxrule`` -``shadowsep`` - The separation between contents and frame for contents_ and - :dudir:`topic` boxes. +.. important:: - See :ref:`additionalcss` for the alias ``div.topic_padding``. + 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. - Default: ``5pt`` +``shadowsep`` + 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 ````, ``div.``, ``sphinx`` :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 ```` 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`. + - ``_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 ``=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`. + - | ``_border-top-left-radius``, | ``_border-top-right-radius``, | ``_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. - ``_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`. + - | ``_border-TeXcolor``, | ``_background-TeXcolor``, | ``_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 ``_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._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 ``\sphinxstyletitle`` 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 ``\sphinxstyletitle`` commands, which + employ the ``\sphinxdotitlerow`` LaTeX command. See :ref:`latex-macros`. - ``div._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. + + .. 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``. - .. 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. + .. 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 diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 5c5f2f7a606..0d9a5ddc747 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -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,10 +793,19 @@ % 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, - div.topic_background-TeXcolor=sphinx-admonition-bgcolor, - div.topic_box-shadow-TeXcolor={RGB}{108,108,108}, - } + % 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 + } % 7.4.0 lets all types of admonitions style especially their titlss. @@ -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 diff --git a/sphinx/texinputs/sphinxlatexadmonitions.sty b/sphinx/texinputs/sphinxlatexadmonitions.sty index 0f49acacf5e..2d50b2eb313 100644 --- a/sphinx/texinputs/sphinxlatexadmonitions.sty +++ b/sphinx/texinputs/sphinxlatexadmonitions.sty @@ -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} 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,16 +333,24 @@ \spx@boxes@withshadowfalse \sphinxcolorlet{spx@boxes@backgroundcolor}{sphinx#1TtlBgColor}% \spx@boxes@fcolorbox{% - \makebox[\linewidth][l]{% - \textcolor{sphinx#1TtlFgColor}{% + \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 % for reasons of fall-back \spx@faIcon definition in sphinx.sty % 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: diff --git a/sphinx/texinputs/sphinxlatexshadowbox.sty b/sphinx/texinputs/sphinxlatexshadowbox.sty index 7fffac22ca5..53a333845aa 100644 --- a/sphinx/texinputs/sphinxlatexshadowbox.sty +++ b/sphinx/texinputs/sphinxlatexshadowbox.sty @@ -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: sphinxTextColor and +% spx@@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 diff --git a/sphinx/texinputs/sphinxlatexstyletext.sty b/sphinx/texinputs/sphinxlatexstyletext.sty index 962971d22d4..d083cd96a83 100644 --- a/sphinx/texinputs/sphinxlatexstyletext.sty +++ b/sphinx/texinputs/sphinxlatexstyletext.sty @@ -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} diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index daee856f918..0f2ffc29f0f 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -585,13 +585,22 @@ def depart_problematic(self, node: Element) -> None: 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,7 +663,10 @@ def visit_title(self, node: Element) -> None: self.body.append(fr'\{self.sectionnames[-1]}{short}{{') self.context.append('}' + CR + self.hypertarget_to(node.parent)) elif isinstance(parent, nodes.topic): - self.body.append(r'\sphinxstyletopictitle{') + 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): self.body.append(r'\sphinxstylesidebartitle{') diff --git a/tests/roots/test-latex-contents-topic-sidebar/conf.py b/tests/roots/test-latex-contents-topic-sidebar/conf.py new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/roots/test-latex-contents-topic-sidebar/index.rst b/tests/roots/test-latex-contents-topic-sidebar/index.rst new file mode 100644 index 00000000000..d47e867f64d --- /dev/null +++ b/tests/roots/test-latex-contents-topic-sidebar/index.rst @@ -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 diff --git a/tests/roots/test-root/conf.py b/tests/roots/test-root/conf.py index 1cc5c2f8fc7..21ec2922e97 100644 --- a/tests/roots/test-root/conf.py +++ b/tests/roots/test-root/conf.py @@ -70,10 +70,15 @@ % 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}, diff --git a/tests/test_builders/test_build_latex.py b/tests/test_builders/test_build_latex.py index 1d474f67691..2aa4e0ea565 100644 --- a/tests/test_builders/test_build_latex.py +++ b/tests/test_builders/test_build_latex.py @@ -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