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

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

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 <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.

doc/latex.rst

@@ -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
+    This legacy option sets the padding (same in all directions) simultaneously
-    :dudir:`topic` boxes.
+    for the :dudir:`topic`, contents_, and :dudir:`sidebar` directives.
-
-    See :ref:`additionalcss` for the alias ``div.topic_padding``.
-
-    Default: ``5pt``
 
 ``shadowsize``
-    The width of the lateral "shadow" to the right and bottom.
+    This legacy option sets the shadow width simultaneously for the
-
+    :dudir:`topic`, contents_, and :dudir:`sidebar` directives.
-    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.
 
 ``shadowrule``
-    The width of the frame around :dudir:`topic` boxes.  See also
+    This legacy option sets the border-width (same on all sides) simultaneously
-    :ref:`additionalcss` for ``div.topic_border-width``.
+    for the :dudir:`topic`, contents_, and :dudir:`sidebar` directives.
-
-    Default: ``\fboxrule``
 
 .. 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``
+   :rst:dir:`literalinclude`, ``pre``, ``sphinxVerbatim``
-   contents_, ``div.topic``, ``sphinxShadowBox``
+   :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
+  * ``6pt``, ``7pt``, ``6pt``, ``7pt`` for :dudir:`topic`,
-    contents_ directive,
+  * ``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
+  * ``8pt`` for all corners of :dudir:`topic`,
-    straight,
+  * ``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)
+  .. versionchanged:: 8.1.0
-     rounded corners.
+     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``,
+  The x-offset and y-offset may be negative.  A negative x-offset means
-  *except* for the :dudir:`topic` or contents_ directives, for which it is
+  that the shadow is on the left.  The shadow extends into the page margin,
-  ``4pt 4pt``, i.e. the shadow has a width of ``4pt`` and extends to the right
+  whether the offset is positive or negative.
-  and below the frame.  The lateral shadow then extends into the page right
+
-  margin.
+  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
+    :rst:dir:`seealso` and :rst:dir:`todo`) as well as of :dudir:`topic`,
-    contents_ directives.
+    contents_ and :dudir:`sidebar` directives.
-  - ``{HTML}{940000}`` is border color or :dudir:`warning`-type admonitions,
+  - ``{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
+  The only directives displaying a shadow per default are contents_ and
-  contents_ (handled identically at LaTeX level) and their shadow color is
+  :dudir:`sidebar`.  The shadow-color for the former is ``{HTML}{6C6C6C}``
-  ``{HTML}{6C6C6C}``.  For all others the default shadow color is black.
+  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
+The next keys, for admonitions, :dudir:`topic`, contents_, and
-default colors are the ones applying to the current HTML rendering of Sphinx
+:dudir:`sidebar`, were all three added at 7.4.0 (and 8.1.0 for the latter three).
-own docs at https://www.sphinx-doc.org.
 
 - ``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
+     definitions for the various ``\sphinxstyle<type>title`` commands, which
-     :ref:`latex-macros`.  Custom redefinitions of these commands are
+     employ the ``\sphinxdotitlerow`` LaTeX command.  See :ref:`latex-macros`.
-     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.
 
 - ``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
+- For :rst:dir:`code-block` or :rst:dir:`literalinclude`, padding and
-  one) will go into the margin; the code lines remain at the same place
+  border-width and shadow (if any) will go into the margin; the code
-  independently of the values of the padding and border-width, except for
+  lines remain at the same place independently of the values of the padding
-  being shifted vertically of course to not overwrite other text due to the
+  and border-width, except for being shifted vertically of course to not
-  width of the border or external shadow.
+  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
+- For the other directives, shadows extend horizontally into the page margins,
-  page margin, but the border and the extra padding are kept within the text
+  but the border and the extra padding are kept within the text area.
-  area.  Same for admonitions.
 
-- The contents_ and :dudir:`topic` directives are governed by the same options
+- :rst:dir:`code-block` and :rst:dir:`literalinclude` use the same LaTeX
-  with ``div.topic`` prefix: the Sphinx LaTeX mark-up uses for both directives
+  environment and commands and are not separately customizable.
-  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...
 
 
 LaTeX macros and environments
@@ -1572,30 +1577,34 @@ Macros
      ``\sphinxstyleliteralintitle``;   ``\sphinxcode{#1}``
      ``\sphinxstylecodecontinued``;    ``{\footnotesize(#1)}}``
      ``\sphinxstylecodecontinues``;    ``{\footnotesize(#1)}}``
-     ``\sphinxstylenotetitle``; ``\sphinxdotitlerowwithicon{note}{#1}``
+     ``\sphinxstylenotetitle``;        ``\sphinxdotitlerow{note}{#1}``
-     ``\sphinxstylehinttitle``; ``\sphinxdotitlerowwithicon{hint}{#1}``
+     ``\sphinxstylehinttitle``;        ``\sphinxdotitlerow{hint}{#1}``
-     ``\sphinxstyleimportanttitle``;   *similar*
+     ``\sphinxstyleimportanttitle``;   ``\sphinxdotitlerow{important}{#1}``
-     ``\sphinxstyletiptitle``;         *similar*
+     ``\sphinxstyletiptitle``;         ``\sphinxdotitlerow{tip}{#1}``
-     ``\sphinxstylewarningtitle``;     *similar*
+     ``\sphinxstylewarningtitle``;     ``\sphinxdotitlerow{warning}{#1}``
-     ``\sphinxstylecautiontitle``;     *similar*
+     ``\sphinxstylecautiontitle``;     ``\sphinxdotitlerow{caution}{#1}``
-     ``\sphinxstyleattentiontitle``;   *similar*
+     ``\sphinxstyleattentiontitle``;   ``\sphinxdotitlerow{attention}{#1}``
-     ``\sphinxstyledangertitle``;      *similar*
+     ``\sphinxstyledangertitle``;      ``\sphinxdotitlerow{danger}{#1}``
-     ``\sphinxstyleerrortitle``;       *similar*
+     ``\sphinxstyleerrortitle``;       ``\sphinxdotitlerow{error}{#1}``
-     ``\sphinxstyleseealsotitle``;     *similar*
+     ``\sphinxstyleseealsotitle``;     ``\sphinxdotitlerow{seealso}{#1}``
-     ``\sphinxstyletodotitle``;        *similar*
+     ``\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
+     To let this table fit on the page width in PDF output we have lied a bit.
-     and the actual definition of ``\sphinxstylenotetitle`` is:
+     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,
+  .. versionadded:: 7.4.0
-     whose first argument is the admonition type, so that it can recover
+     Added the ``\sphinxdotitlerowwithicon`` LaTeX command.
-     the associated colours and icon for the title row, and the second
-     argument gets typeset after the icon.
 
-  .. todo:: The fact that we must employ ``\sphinxremovefinalcolon`` is a
+  .. versionchanged:: 8.1.0
-            legacy artefact from old ill-designed Sphinx LaTeX writer,
+     ``\sphinxdotitlerowwithicon`` now detects automatically if an icon is
-            which postfixes (still today) the title with a colon automatically.
+     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``
+  It takes one argument, namely the localization of ``Todo``
-  followed with a colon.
+  (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

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
+% let legacy shadowsep key set all topic/contents/sidebar padding
-\expandafter\let\expandafter\KV@sphinx@shadowsep\csname KV@sphinx@div.topic_padding\endcsname
+% 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
+        % sphinxpackageboxes.sty.
-        % 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.
   \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@tempa{spx@contents@} {div.contents_}
-    \spx@topic@shadow@setter 4pt 4pt {} \@nnil
+\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,
+    % 8.1.0 styles separately topic/contents/sidebar
-                     div.topic_background-TeXcolor=sphinx-admonition-bgcolor,
+    % topic has no shadow but we keep 7.4.0 color in case it gets needed
-                     div.topic_box-shadow-TeXcolor={RGB}{108,108,108},
+    \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

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
+% - Also redefinable by user are the one-argument commands
-%   one-argument macros \sphinxstylenotetitle, \sphinxstylewarningtitle, etc
+%   * \sphinxstylenotetitle,
-%   which can be redefined.  Their default is to use \sphinxdotitlerowwithicon
+%   * \sphinxstylewarningtitle,
-%   to typeset the title in a coloured header row at top of the
+%   * etc.... one for each admonition type (also seealso and todo).
-%   admonition. (new with 7.4.0)
+%
+% - 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,16 +333,24 @@
      \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
-         \textcolor{sphinx#1TtlFgColor}{%
+                               % 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\sphinxstylenotetitle     [1]{\sphinxdotitlerow{note}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstylehinttitle     [1]{\sphinxdotitlerowwithicon{hint}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstylehinttitle     [1]{\sphinxdotitlerow{hint}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstyleimportanttitle[1]{\sphinxdotitlerowwithicon{important}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstyleimportanttitle[1]{\sphinxdotitlerow{important}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstyletiptitle      [1]{\sphinxdotitlerowwithicon{tip}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstyletiptitle      [1]{\sphinxdotitlerow{tip}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstylewarningtitle  [1]{\sphinxdotitlerowwithicon{warning}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstylewarningtitle  [1]{\sphinxdotitlerow{warning}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstylecautiontitle  [1]{\sphinxdotitlerowwithicon{caution}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstylecautiontitle  [1]{\sphinxdotitlerow{caution}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstyleattentiontitle[1]{\sphinxdotitlerowwithicon{attention}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstyleattentiontitle[1]{\sphinxdotitlerow{attention}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstyledangertitle   [1]{\sphinxdotitlerowwithicon{danger}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstyledangertitle   [1]{\sphinxdotitlerow{danger}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstyleerrortitle    [1]{\sphinxdotitlerowwithicon{error}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstyleerrortitle    [1]{\sphinxdotitlerow{error}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstyleseealsotitle  [1]{\sphinxdotitlerowwithicon{seealso}{\sphinxremovefinalcolon{#1}}}
+\newcommand\sphinxstyleseealsotitle  [1]{\sphinxdotitlerow{seealso}{\sphinxremovefinalcolon{#1}}}
-\newcommand\sphinxstyletodotitle     [1]{\sphinxdotitlerowwithicon{todo}{\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:

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: 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
+    \@nameuse{ifspx@#1@withtextcolor}%
-      \color{sphinxtopicTextColor}%
+      \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

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}

sphinx/writers/latex.py

@@ -585,13 +585,22 @@ class LaTeXTranslator(SphinxTranslator):
         self.body.append('}')
 
     def visit_topic(self, node: Element) -> None:
-        self.in_minipage = 1
+        self.in_minipage += 1
-        self.body.append(CR + r'\begin{sphinxShadowBox}' + CR)
+        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.in_minipage -= 1
-        self.body.append(r'\end{sphinxShadowBox}' + CR)
+        self.body.append(self.context.pop())
-    visit_sidebar = visit_topic
+
+    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 @@ 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):
-            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{')

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

tests/roots/test-root/conf.py

@@ -70,10 +70,15 @@ latex_elements = {
 %
   shadowrule=1pt,
   shadowsep=10pt,
-  shadowsize=10pt,
+  shadowsize=-10pt,
-  div.topic_border-width=2pt,% alias to shadowrule
+  div.topic_border-width=2pt,
-  div.topic_padding=6pt,% alias to shadowsep
+  div.topic_padding=6pt,
-  div.topic_box-shadow=5pt,% overrides/alias shadowsize
+  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},

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