Sphinx 8.0.1__py3-none-any.whl → 8.1.0__py3-none-any.whl

sphinx/testing/util.py

@@ -29,7 +29,7 @@ if TYPE_CHECKING:
     from docutils.nodes import Node
 
 
-def assert_node(node: Node, cls: Any = None, xpath: str = "", **kwargs: Any) -> None:
+def assert_node(node: Node, cls: Any = None, xpath: str = '', **kwargs: Any) -> None:
     if cls:
         if isinstance(cls, list):
             assert_node(node, cls[0], xpath=xpath, **kwargs)
@@ -37,36 +37,43 @@ def assert_node(node: Node, cls: Any = None, xpath: str = "", **kwargs: Any) ->
                 if isinstance(cls[1], tuple):
                     assert_node(node, cls[1], xpath=xpath, **kwargs)
                 else:
-                    assert isinstance(node, nodes.Element), \
-                        'The node%s does not have any children' % xpath
-                    assert len(node) == 1, \
-                        'The node%s has %d child nodes, not one' % (xpath, len(node))
-                    assert_node(node[0], cls[1:], xpath=xpath + "[0]", **kwargs)
+                    assert (
+                        isinstance(node, nodes.Element)
+                    ), f'The node{xpath} does not have any children'  # fmt: skip
+                    assert (
+                        len(node) == 1
+                    ), f'The node{xpath} has {len(node)} child nodes, not one'
+                    assert_node(node[0], cls[1:], xpath=xpath + '[0]', **kwargs)
         elif isinstance(cls, tuple):
-            assert isinstance(node, list | nodes.Element), \
-                'The node%s does not have any items' % xpath
-            assert len(node) == len(cls), \
-                'The node%s has %d child nodes, not %r' % (xpath, len(node), len(cls))
+            assert (
+                isinstance(node, list | nodes.Element)
+            ), f'The node{xpath} does not have any items'  # fmt: skip
+            assert (
+                len(node) == len(cls)
+            ), f'The node{xpath} has {len(node)} child nodes, not {len(cls)!r}'  # fmt: skip
             for i, nodecls in enumerate(cls):
-                path = xpath + "[%d]" % i
+                path = xpath + f'[{i}]'
                 assert_node(node[i], nodecls, xpath=path, **kwargs)
         elif isinstance(cls, str):
             assert node == cls, f'The node {xpath!r} is not {cls!r}: {node!r}'
         else:
-            assert isinstance(node, cls), \
-                f'The node{xpath} is not subclass of {cls!r}: {node!r}'
+            assert (
+                isinstance(node, cls)
+            ), f'The node{xpath} is not subclass of {cls!r}: {node!r}'  # fmt: skip
 
     if kwargs:
-        assert isinstance(node, nodes.Element), \
-            'The node%s does not have any attributes' % xpath
+        assert (
+            isinstance(node, nodes.Element)
+        ), f'The node{xpath} does not have any attributes'  # fmt: skip
 
         for key, value in kwargs.items():
             if key not in node:
                 if (key := key.replace('_', '-')) not in node:
                     msg = f'The node{xpath} does not have {key!r} attribute: {node!r}'
                     raise AssertionError(msg)
-            assert node[key] == value, \
-                f'The node{xpath}[{key}] is not {value!r}: {node[key]!r}'
+            assert (
+                node[key] == value
+            ), f'The node{xpath}[{key}] is not {value!r}: {node[key]!r}'
 
 
 # keep this to restrict the API usage and to have a correct return type
@@ -86,7 +93,7 @@ class SphinxTestApp(sphinx.application.Sphinx):
 
     It is recommended to use::
 
-        @pytest.mark.sphinx('html')
+        @pytest.mark.sphinx('html', testroot='root')
         def test(app):
             app = ...
 
@@ -117,11 +124,14 @@ class SphinxTestApp(sphinx.application.Sphinx):
         parallel: int = 0,
         # additional arguments at the end to keep the signature
         verbosity: int = 0,  # argument is not in the same order as in the superclass
-        keep_going: bool = False,
         warningiserror: bool = False,  # argument is not in the same order as in the superclass
+        pdb: bool = False,
+        exception_on_warning: bool = False,
         # unknown keyword arguments
         **extras: Any,
     ) -> None:
+        self._builder_name = buildername
+
         assert srcdir is not None
 
         if verbosity == -1:
@@ -135,7 +145,7 @@ class SphinxTestApp(sphinx.application.Sphinx):
             # but allow the stream to be /dev/null by passing verbosity=-1
             status = None if quiet else StringIO()
         elif not isinstance(status, StringIO):
-            err = "%r must be an io.StringIO object, got: %s" % ('status', type(status))
+            err = f"'status' must be an io.StringIO object, got: {type(status)}"
             raise TypeError(err)
 
         if warning is None:
@@ -143,7 +153,7 @@ class SphinxTestApp(sphinx.application.Sphinx):
             # but allow the stream to be /dev/null by passing verbosity=-1
             warning = None if quiet else StringIO()
         elif not isinstance(warning, StringIO):
-            err = '%r must be an io.StringIO object, got: %s' % ('warning', type(warning))
+            err = f"'warning' must be an io.StringIO object, got: {type(warning)}"
             raise TypeError(err)
 
         self.docutils_conf_path = srcdir / 'docutils.conf'
@@ -167,16 +177,36 @@ class SphinxTestApp(sphinx.application.Sphinx):
 
         try:
             super().__init__(
-                srcdir, confdir, outdir, doctreedir, buildername,
-                confoverrides=confoverrides, status=status, warning=warning,
-                freshenv=freshenv, warningiserror=warningiserror, tags=tags,
-                verbosity=verbosity, parallel=parallel, keep_going=keep_going,
-                pdb=False,
+                srcdir,
+                confdir,
+                outdir,
+                doctreedir,
+                buildername,
+                confoverrides=confoverrides,
+                status=status,
+                warning=warning,
+                freshenv=freshenv,
+                warningiserror=warningiserror,
+                tags=tags,
+                verbosity=verbosity,
+                parallel=parallel,
+                pdb=pdb,
+                exception_on_warning=exception_on_warning,
             )
         except Exception:
             self.cleanup()
             raise
 
+    def _init_builder(self) -> None:
+        # override the default theme to 'basic' rather than 'alabaster'
+        # for test independence
+
+        if 'html_theme' in self.config._overrides:
+            pass  # respect overrides
+        elif 'html_theme' in self.config and self.config.html_theme == 'alabaster':
+            self.config.html_theme = self.config._overrides.get('html_theme', 'basic')
+        super()._init_builder()
+
     @property
     def status(self) -> StringIO:
         """The in-memory text I/O for the application status messages."""
@@ -198,9 +228,11 @@ class SphinxTestApp(sphinx.application.Sphinx):
             os.remove(self.docutils_conf_path)
 
     def __repr__(self) -> str:
-        return f'<{self.__class__.__name__} buildername={self.builder.name!r}>'
+        return f'<{self.__class__.__name__} buildername={self._builder_name!r}>'
 
-    def build(self, force_all: bool = False, filenames: list[str] | None = None) -> None:
+    def build(
+        self, force_all: bool = False, filenames: list[str] | None = None
+    ) -> None:
         self.env._pickled_doctree_cache.clear()
         super().build(force_all, filenames)
 
@@ -212,7 +244,9 @@ class SphinxTestAppWrapperForSkipBuilding(SphinxTestApp):
     if it has already been built and there are any output files.
     """
 
-    def build(self, force_all: bool = False, filenames: list[str] | None = None) -> None:
+    def build(
+        self, force_all: bool = False, filenames: list[str] | None = None
+    ) -> None:
         if not os.listdir(self.outdir):
             # if listdir is empty, do build.
             super().build(force_all, filenames)

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
@@ -156,6 +156,7 @@
 \DeclareStringOption[-1]{numfigreset}
 \DeclareBoolOption[false]{nonumfigreset}
 \DeclareBoolOption[false]{mathnumfig}
+\DeclareStringOption[.]{mathnumsep}
 \define@key{sphinx}{bookmarksdepth}{\AtBeginDocument{\hypersetup{bookmarksdepth=#1}}}
 \AtBeginDocument{\define@key{sphinx}{bookmarksdepth}{\hypersetup{bookmarksdepth=#1}}}
 % \DeclareBoolOption[false]{usespart}% not used
@@ -350,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}
 %
@@ -397,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}
@@ -444,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}
@@ -462,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
 %
@@ -491,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@
@@ -522,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@}
@@ -555,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
   }%
@@ -569,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_}
@@ -584,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
 }%
 
@@ -638,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@}
@@ -690,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}
@@ -731,7 +781,7 @@
     \spx@tempa{div.important_}  {important}
     \spx@tempa{div.tip_}        {tip}
 
-    % Add "legacy" hintTeXextras etc... 
+    % Add "legacy" hintTeXextras etc...
     \def\spx@tempa#1#2{% #1 = CSS like option prefix, #2 = legacy option prefix
       \expandafter\let\csname KV@sphinx@#2TeXextras\expandafter\endcsname
                       \csname KV@sphinx@#1TeXextras\endcsname
@@ -743,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.
@@ -799,15 +858,21 @@
   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
 % We try to
 % - get Sphinx PDF builds to process fine in absence of fontawesome5
 % - use fontawesome5 if present, but not if user prefers another package
-% - provide an interface for using other LaTeX code for icons  
+% - provide an interface for using other LaTeX code for icons
 % - provide an interface for using some other package than fontawesome5
 % Indeed we can't load fontawesome5 unconditionally even if available,
 % as it proves incompatible with fontawesome package.
@@ -881,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
@@ -945,9 +1013,9 @@
 %% PASS OPTIONS
 %
 % pass options to hyperref; it must not have been loaded already
-\input{sphinxoptionshyperref.sty}
+\RequirePackage{sphinxoptionshyperref}
 % pass options to geometry; it must not have been loaded already
-\input{sphinxoptionsgeometry.sty}
+\RequirePackage{sphinxoptionsgeometry}
 
 
 %% COLOR (general)
@@ -986,7 +1054,7 @@
 %
 % It will always be needed, so let's load it here
 \RequirePackage{graphicx}
-\input{sphinxlatexgraphics.sty}
+\RequirePackage{sphinxlatexgraphics}
 
 
 %% FRAMED ENVIRONMENTS
@@ -1051,14 +1119,14 @@
                 addstrut=false,
                }%
 \RequirePackage{sphinxpackageboxes}
-\input{sphinxlatexadmonitions.sty}
-\input{sphinxlatexliterals.sty}
-\input{sphinxlatexshadowbox.sty}
+\RequirePackage{sphinxlatexadmonitions}
+\RequirePackage{sphinxlatexliterals}
+\RequirePackage{sphinxlatexshadowbox}
 
 
 %% CONTAINERS
 %
-\input{sphinxlatexcontainers.sty}
+\RequirePackage{sphinxlatexcontainers}
 
 
 %% PYGMENTS
@@ -1068,17 +1136,17 @@
 
 %% TABLES
 %
-\input{sphinxlatextables.sty}
+\RequirePackage{sphinxlatextables}
 
 
 %% NUMBERING OF FIGURES, TABLES, AND LITERAL BLOCKS
 %
-\input{sphinxlatexnumfig.sty}
+\RequirePackage{sphinxlatexnumfig}
 
 
 %% LISTS
 %
-\input{sphinxlatexlists.sty}
+\RequirePackage{sphinxlatexlists}
 
 
 %% FOOTNOTES
@@ -1108,19 +1176,19 @@
 
 %% INDEX, BIBLIOGRAPHY, APPENDIX, TABLE OF CONTENTS
 %
-\input{sphinxlatexindbibtoc.sty}
+\RequirePackage{sphinxlatexindbibtoc}
 
 
 %% STYLING
 %
-\input{sphinxlatexstylepage.sty}
-\input{sphinxlatexstyleheadings.sty}
-\input{sphinxlatexstyletext.sty}
+\RequirePackage{sphinxlatexstylepage}
+\RequirePackage{sphinxlatexstyleheadings}
+\RequirePackage{sphinxlatexstyletext}
 
 
 %% MODULE RELEASE DATA AND OBJECT DESCRIPTIONS
 %
-\input{sphinxlatexobjects.sty}
+\RequirePackage{sphinxlatexobjects}
 
 
 % FIXME: this line should be dropped, as "9" is default anyhow.

sphinx/texinputs/sphinxlatexadmonitions.sty

@@ -1,15 +1,12 @@
 %% NOTICES AND ADMONITIONS
 %
 % change this info string if making any custom modification
-\ProvidesFile{sphinxlatexadmonitions.sty}[2024/07/01 v7.4.0 admonitions]
+\ProvidesPackage{sphinxlatexadmonitions}[2024/07/28 v8.1.0 admonitions]
 
 % Provides support for this output mark-up from Sphinx latex writer:
 %
 % - sphinxseealso environment added at 6.1.0.
 %
-% At 7.4.0 it too now uses sphinxheavybox, and has the same associated
-% sphinxsetup CSS keys as admonitions do.
-%
 % - sphinxtodo environment added at 7.4.0.
 %
 % - sphinxadmonition (environment)
@@ -19,16 +16,21 @@
 %     sphinxheavybox since 6.2.0),
 %   - warning, caution, attention, danger, error to use sphinxheavybox.
 %
-% At 7.4.0 all admonitions use sphinxheavybox.
+%   Since 7.4.0 all admonitions use sphinxheavybox.
 %
 % - All environments sphinxnote, sphinxwarning, etc... can be redefined as
 %   will by user. Thay have a single parameter #1 which is the title.
 %
-% - The default sphinxnote, sphinxwarning, etc... use associated
-%   one-argument macros \sphinxstylenotetitle, \sphinxstylewarningtitle, etc
-%   which can be redefined.  Their default is to use \sphinxdotitlerowwithicon
-%   to typeset the title in a coloured header row at top of the
-%   admonition. (new with 7.4.0)
+% - Also redefinable by user are the one-argument commands
+%   * \sphinxstylenotetitle,
+%   * \sphinxstylewarningtitle,
+%   * etc.... one for each admonition type (also seealso and todo).
+%
+% - At 7.4.0, all commands of previous item use \sphinxdotitlerow.
+%   (the 7.4.0 name, still usable, was \sphinxdotitlerowwithicon; the 8.1.0
+%   version is also used for topic, contents and sidebar directives, see
+%   sphinxlatexshadowbox.sty, and handles both "with icon" and "without
+%   icon" situations).
 %
 % The sphinxlightbox environment is kept for backward compatiblity, for user
 % custom code which used it via custom definitions done in preamble or via
@@ -42,20 +44,21 @@
 % (the 7.4.0 redefined \sphinxstylenotetitle will not work in sphinxlightbox,
 %  so \sphinxstrong{#1}<space> which was its former default is used above).
 
-%
-% Requires:
-\RequirePackage{sphinxpackageboxes}
-% 7.4.0 removes unneeded \spx@boxes@border
-\RequirePackage{framed}% used by sphinxheavybox
-%
 % Dependencies (they do not need to be defined at time of loading):
 %
 % - of course the various colour and dimension options handled via sphinx.sty
-%
 % - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty
+% - \savenotes/\spewnotes from sphinxpackagefootnote.sty
+% - \ifspx@inframed defined in sphinx.sty
+% - \spx@boxes@fcolorbox@setup from sphinxpackageboxes.sty
+%
+\RequirePackage{framed}
+% Those are required either before or after by sphinx.sty anyhow, but for
+% clarity we list them here:
+\RequirePackage{sphinxlatexgraphics}
+\RequirePackage{sphinxpackagefootnote}
+\RequirePackage{sphinxpackageboxes}
 %
-% - \savenotes/\spewnotes from sphinxpackagefootnote (for sphinxheavybox)
-
 % Provides: (also in sphinxlatexliterals.sty)
 % Only needed here by legacy (deprecated) sphinxlightbox environment.
 \providecommand*\sphinxvspacefixafterfrenchlists{%
@@ -300,10 +303,15 @@
   % workaround some LaTeX "feature" of \end command (i.e. can't use "sphinx#1" here)
   {\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp}
 
+% TODO: allow these next three settings to be customized individually.
+%       This can however already be done at user level by \renewcommand
+%       inside renew'ed environments sphinxnote, sphinxhint etc...
 \newcommand\sphinxtitlerowtoppadding{5pt}
 \newcommand\sphinxtitlerowbottompadding{3pt}
 \newcommand\sphinxtitlerowaftericonspacecmd{\hskip0.5em\relax}
-\newcommand\sphinxdotitlerowwithicon[2]{% #1=type, #2=heading (without final colon)
+% 7.4.0 used this longer name:
+\newcommand\sphinxdotitlerowwithicon{\sphinxdotitlerow}
+\newcommand\sphinxdotitlerow[2]{% #1=type, #2=heading (without final colon)
    \begingroup
      \kern-\spx@boxes@padding@top
      \parskip\z@skip % the \parskip business is a workaround to a vertical
@@ -325,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:

sphinx/texinputs/sphinxlatexcontainers.sty

@@ -1,7 +1,7 @@
 %% CONTAINER DIRECTIVES
 %
 % change this info string if making any custom modification
-\ProvidesFile{sphinxlatexcontainers.sty}[2021/05/03 containers]
+\ProvidesPackage{sphinxlatexcontainers}[2021/05/03 containers]
 
 % The purpose of this file is to provide a dummy environment sphinxclass which
 % will be inserted for each class in each container directive. The class name