Sphinx 7.4.4__tar.gz → 7.4.6__tar.gz

{sphinx-7.4.4 → sphinx-7.4.6}/CHANGES.rst

@@ -1,3 +1,30 @@
+Release 7.4.6 (released Jul 18, 2024)
+=====================================
+
+Bugs fixed
+----------
+
+* #12859, #9743, #12609: autosummary: Do not add the package prefix when
+  generating autosummary directives for modules within a package.
+  Patch by Adam Turner.
+* #12613: Reduce log severity for ambiguity detection during inventory loading.
+  Patch by James Addison.
+
+Release 7.4.5 (released Jul 16, 2024)
+=====================================
+
+Bugs fixed
+----------
+
+* #12593, #12600: Revert coercing the type of selected :confval:`html_sidebars`
+  values to a list.
+  Log an error message when string values are detected.
+  Patch by Adam Turner.
+* #12594: LaTeX: since 7.4.0, :rst:dir:`seealso` and other "light" admonitions
+  now break PDF builds if they contain a :dudir:`figure` directive; and also
+  if they are contained in a table cell (rendered by ``tabulary``).
+  Patch by Jean-François B.
+
 Release 7.4.4 (released Jul 15, 2024)
 =====================================
 
@@ -159,11 +186,13 @@ Bugs fixed
   Patch by Matthias Geier.
 * #12224: Properly detect WebP files.
   Patch by Benjamin Cabé.
-* #12380: LaTeX: Footnote mark sometimes indicates ``Page N`` where ``N`` is
-  the current page number and the footnote does appear on that same page.
+* #12380: LaTeX: Avoid footnote markers ``Page N`` when ``N`` is already
+  the current page number.
   Patch by Jean-François B.
 * #12410: LaTeX: for French and ``'lualatex'`` as :confval:`latex_engine`
-  ``polyglossia`` and not ``babel`` is used (contrarily to ``'xelatex'``).
+  use ``babel`` as with ``'xelatex'`` (and not ``polyglossia``).
+  Patch by Jean-François B.
+* #12520: LaTeX: let :rst:dir:`todolist` produce correct hyperlinks in PDF.
   Patch by Jean-François B.
 * #12416: Ensure that configuration setting aliases are always synchronised
   when one value or the other is modified.

{sphinx-7.4.4 → sphinx-7.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: Sphinx
-Version: 7.4.4
+Version: 7.4.6
 Summary: Python documentation generator
 Author-email: Georg Brandl <georg@python.org>
 Requires-Python: >=3.9

{sphinx-7.4.4 → sphinx-7.4.6}/sphinx/__init__.py

@@ -1,6 +1,6 @@
 """The Sphinx documentation toolchain."""
 
-__version__ = '7.4.4'
+__version__ = '7.4.6'
 __display_version__ = __version__  # used for command line version
 
 # Keep this file executable as-is in Python 3!
@@ -27,7 +27,7 @@ warnings.filterwarnings(
 #:
 #: .. versionadded:: 1.2
 #:    Before version 1.2, check the string ``sphinx.__version__``.
-version_info = (7, 4, 4, 'final', 0)
+version_info = (7, 4, 6, 'final', 0)
 
 package_dir = os.path.abspath(os.path.dirname(__file__))
 

{sphinx-7.4.4 → sphinx-7.4.6}/sphinx/builders/html/__init__.py

@@ -982,11 +982,10 @@ class StandaloneHTMLBuilder(Builder):
                 matched = pattern
                 sidebars = pat_sidebars
 
-        if len(sidebars) == 0:
-            # keep defaults
-            pass
-
-        ctx['sidebars'] = list(sidebars)
+        # See error_on_html_sidebars_string_values.
+        # Replace with simple list coercion in Sphinx 8.0
+        # xref: RemovedInSphinx80Warning
+        ctx['sidebars'] = sidebars
 
     # --------- these are overwritten by the serialization builder
 
@@ -1287,6 +1286,25 @@ def validate_html_favicon(app: Sphinx, config: Config) -> None:
         config.html_favicon = None
 
 
+def error_on_html_sidebars_string_values(app: Sphinx, config: Config) -> None:
+    """Support removed in Sphinx 2."""
+    errors = {}
+    for pattern, pat_sidebars in config.html_sidebars.items():
+        if isinstance(pat_sidebars, str):
+            errors[pattern] = [pat_sidebars]
+    if not errors:
+        return
+    msg = __("Values in 'html_sidebars' must be a list of strings. "
+             "At least one pattern has a string value: %s. "
+             "Change to `html_sidebars = %r`.")
+    bad_patterns = ', '.join(map(repr, errors))
+    fixed = config.html_sidebars | errors
+    logger.error(msg, bad_patterns, fixed)
+    # Enable hard error in next major version.
+    # xref: RemovedInSphinx80Warning
+    # raise ConfigError(msg % (bad_patterns, fixed))
+
+
 def error_on_html_4(_app: Sphinx, config: Config) -> None:
     """Error on HTML 4."""
     if config.html4_writer:
@@ -1357,6 +1375,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     app.connect('config-inited', validate_html_static_path, priority=800)
     app.connect('config-inited', validate_html_logo, priority=800)
     app.connect('config-inited', validate_html_favicon, priority=800)
+    app.connect('config-inited', error_on_html_sidebars_string_values, priority=800)
     app.connect('config-inited', error_on_html_4, priority=800)
     app.connect('builder-inited', validate_math_renderer)
     app.connect('html-page-context', setup_resource_paths)

{sphinx-7.4.4 → sphinx-7.4.6}/sphinx/ext/autosummary/generate.py

@@ -330,10 +330,6 @@ def generate_autosummary_content(
                     doc, app, obj, {'module'}, imported=True
                 )
                 skip += all_imported_modules
-                imported_modules = [name + '.' + modname for modname in imported_modules]
-                all_imported_modules = [
-                    name + '.' + modname for modname in all_imported_modules
-                ]
                 public_members = getall(obj)
             else:
                 imported_modules, all_imported_modules = [], []
@@ -476,21 +472,22 @@ def _get_modules(
         if modname in skip:
             # module was overwritten in __init__.py, so not accessible
             continue
-        fullname = name + '.' + modname
+        fullname = f'{name}.{modname}'
         try:
             module = import_module(fullname)
-            if module and hasattr(module, '__sphinx_mock__'):
-                continue
         except ImportError:
             pass
+        else:
+            if module and hasattr(module, '__sphinx_mock__'):
+                continue
 
-        items.append(fullname)
+        items.append(modname)
         if public_members is not None:
             if modname in public_members:
-                public.append(fullname)
+                public.append(modname)
         else:
             if not modname.startswith('_'):
-                public.append(fullname)
+                public.append(modname)
     return public, items
 
 

{sphinx-7.4.4 → sphinx-7.4.6}/sphinx/ext/autosummary/templates/autosummary/module.rst

@@ -3,7 +3,7 @@
 .. automodule:: {{ fullname }}
 
    {% block attributes %}
-   {% if attributes %}
+   {%- if attributes %}
    .. rubric:: {{ _('Module Attributes') }}
 
    .. autosummary::
@@ -11,10 +11,10 @@
       {{ item }}
    {%- endfor %}
    {% endif %}
-   {% endblock %}
+   {%- endblock %}
 
-   {% block functions %}
-   {% if functions %}
+   {%- block functions %}
+   {%- if functions %}
    .. rubric:: {{ _('Functions') }}
 
    .. autosummary::
@@ -22,10 +22,10 @@
       {{ item }}
    {%- endfor %}
    {% endif %}
-   {% endblock %}
+   {%- endblock %}
 
-   {% block classes %}
-   {% if classes %}
+   {%- block classes %}
+   {%- if classes %}
    .. rubric:: {{ _('Classes') }}
 
    .. autosummary::
@@ -33,10 +33,10 @@
       {{ item }}
    {%- endfor %}
    {% endif %}
-   {% endblock %}
+   {%- endblock %}
 
-   {% block exceptions %}
-   {% if exceptions %}
+   {%- block exceptions %}
+   {%- if exceptions %}
    .. rubric:: {{ _('Exceptions') }}
 
    .. autosummary::
@@ -44,10 +44,10 @@
       {{ item }}
    {%- endfor %}
    {% endif %}
-   {% endblock %}
+   {%- endblock %}
 
-{% block modules %}
-{% if modules %}
+{%- block modules %}
+{%- if modules %}
 .. rubric:: Modules
 
 .. autosummary::
@@ -57,4 +57,4 @@
    {{ item }}
 {%- endfor %}
 {% endif %}
-{% endblock %}
+{%- endblock %}

{sphinx-7.4.4 → sphinx-7.4.6}/sphinx/ext/todo.py

@@ -215,6 +215,9 @@ def latex_visit_todo_node(self: LaTeXTranslator, node: todo_node) -> None:
         title_node = cast(nodes.title, node[0])
         title = texescape.escape(title_node.astext(), self.config.latex_engine)
         self.body.append('%s:}' % title)
+        self.no_latex_floats += 1
+        if self.table:
+            self.table.has_problematic = True
         node.pop(0)
     else:
         raise nodes.SkipNode
@@ -222,6 +225,7 @@ def latex_visit_todo_node(self: LaTeXTranslator, node: todo_node) -> None:
 
 def latex_depart_todo_node(self: LaTeXTranslator, node: todo_node) -> None:
     self.body.append('\\end{sphinxtodo}\n')
+    self.no_latex_floats -= 1
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:

{sphinx-7.4.4 → sphinx-7.4.6}/sphinx/texinputs/sphinxlatextables.sty

@@ -108,6 +108,7 @@
     \vbox{}% get correct baseline from above
     \LTpre\z@skip\LTpost\z@skip % set to zero longtable's own skips
     \edef\sphinxbaselineskip{\dimexpr\the\dimexpr\baselineskip\relax\relax}%
+    \spx@inframedtrue % message to sphinxheavybox
    }%
 % Compatibility with caption package
 \def\sphinxthelongtablecaptionisattop{%
@@ -121,7 +122,9 @@
 \def\sphinxatlongtableend{\@nobreakfalse % latex3/latex2e#173
     \prevdepth\z@\vskip\sphinxtablepost\relax}%
 % B. Table with tabular or tabulary
-\def\sphinxattablestart{\par\vskip\dimexpr\sphinxtablepre\relax}%
+\def\sphinxattablestart{\par\vskip\dimexpr\sphinxtablepre\relax
+                        \spx@inframedtrue % message to sphinxheavybox
+                        }%
 \let\sphinxattableend\sphinxatlongtableend
 % This is used by tabular and tabulary templates
 \newcommand*\sphinxcapstartof[1]{%

{sphinx-7.4.4 → sphinx-7.4.6}/sphinx/util/inventory.py

@@ -172,8 +172,8 @@ class InventoryFile:
             inv_item: InventoryItem = projname, version, location, dispname
             invdata.setdefault(type, {})[name] = inv_item
         for ambiguity in actual_ambiguities:
-            logger.warning(__("inventory <%s> contains multiple definitions for %s"),
-                           uri, ambiguity, type='intersphinx',  subtype='external')
+            logger.info(__("inventory <%s> contains multiple definitions for %s"),
+                        uri, ambiguity, type='intersphinx',  subtype='external')
         return invdata
 
     @classmethod

{sphinx-7.4.4 → sphinx-7.4.6}/sphinx/writers/latex.py

@@ -306,6 +306,7 @@ class LaTeXTranslator(SphinxTranslator):
         self.in_term = 0
         self.needs_linetrimming = 0
         self.in_minipage = 0
+        # only used by figure inside an admonition
         self.no_latex_floats = 0
         self.first_document = 1
         self.this_is_the_title = 1
@@ -966,11 +967,15 @@ class LaTeXTranslator(SphinxTranslator):
     def visit_seealso(self, node: Element) -> None:
         self.body.append(BLANKLINE)
         self.body.append(r'\begin{sphinxseealso}{%s:}' % admonitionlabels['seealso'] + CR)
+        self.no_latex_floats += 1
+        if self.table:
+            self.table.has_problematic = True
 
     def depart_seealso(self, node: Element) -> None:
         self.body.append(BLANKLINE)
         self.body.append(r'\end{sphinxseealso}')
         self.body.append(BLANKLINE)
+        self.no_latex_floats -= 1
 
     def visit_rubric(self, node: nodes.rubric) -> None:
         if len(node) == 1 and node.astext() in ('Footnotes', _('Footnotes')):
@@ -1512,6 +1517,8 @@ class LaTeXTranslator(SphinxTranslator):
         if self.no_latex_floats:
             align = "H"
         if self.table:
+            # Blank line is needed if text precedes
+            self.body.append(BLANKLINE)
             # TODO: support align option
             if 'width' in node:
                 length = self.latex_image_length(node['width'])
@@ -1580,6 +1587,8 @@ class LaTeXTranslator(SphinxTranslator):
     def visit_admonition(self, node: Element) -> None:
         self.body.append(CR + r'\begin{sphinxadmonition}{note}')
         self.no_latex_floats += 1
+        if self.table:
+            self.table.has_problematic = True
 
     def depart_admonition(self, node: Element) -> None:
         self.body.append(r'\end{sphinxadmonition}' + CR)
@@ -1590,6 +1599,8 @@ class LaTeXTranslator(SphinxTranslator):
         self.body.append(CR + r'\begin{sphinxadmonition}{%s}{%s:}' %
                          (node.tagname, label))
         self.no_latex_floats += 1
+        if self.table:
+            self.table.has_problematic = True
 
     def _depart_named_admonition(self, node: Element) -> None:
         self.body.append(r'\end{sphinxadmonition}' + CR)

{sphinx-7.4.4 → sphinx-7.4.6}/tests/js/searchtools.js

@@ -22,6 +22,7 @@ describe('Basic html theme search', function() {
     }
 
     expect(remainingItems.length).toEqual(0);
+    expect(nextExpected).toEqual(undefined);
   }
 
   describe('terms search', function() {
@@ -137,7 +138,7 @@ describe('Basic html theme search', function() {
 
       expectedRanking = [
         ['relevance', 'Relevance', ''],  /* main title */
-        ['index', 'relevance.Example.relevance', '#module-relevance'],  /* py:class attribute */
+        ['index', 'relevance.Example.relevance', '#relevance.Example.relevance'],  /* py:class attribute */
       ];
 
       searchParameters = Search._parseQuery('relevance');

sphinx-7.4.6/tests/roots/test-ext-autosummary-module_prefix/conf.py

@@ -0,0 +1,8 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('.'))
+
+extensions = [
+    'sphinx.ext.autosummary',
+]

sphinx-7.4.6/tests/roots/test-ext-autosummary-module_prefix/index.rst

@@ -0,0 +1,5 @@
+.. autosummary::
+   :toctree: docs/pkg
+   :recursive:
+
+   pkg

sphinx-7.4.6/tests/roots/test-latex-figure-in-admonition/conf.py

@@ -0,0 +1,3 @@
+extensions = ['sphinx.ext.todo']
+todo_include_todos = True
+exclude_patterns = ['_build']

sphinx-7.4.6/tests/roots/test-latex-figure-in-admonition/index.rst

@@ -0,0 +1,26 @@
+Test Figure in Admonition
+=========================
+
+.. caution::
+
+   This uses a figure in a caution directive.
+
+   .. figure:: img.png
+
+.. note::
+
+   This uses a figure in a note directive.
+
+   .. figure:: img.png
+
+.. seealso::
+
+   This uses a figure in a seealso directive.
+
+   .. figure:: img.png
+
+.. todo::
+
+   This uses a figure in a todo directive.
+
+   .. figure:: img.png

{sphinx-7.4.4 → sphinx-7.4.6}/tests/roots/test-root/markup.txt

@@ -230,6 +230,19 @@ Tables with multirow and multicol:
 
           figure in table
 
+   * - .. warning::
+
+          warning in table
+
+   * - .. seealso::
+
+          figure in a seealso in a table
+
+          .. figure:: img.png
+
+             with a caption
+
+             and a legend
 
 Figures
 -------

{sphinx-7.4.4 → sphinx-7.4.6}/tests/test_builders/test_build_html.py

@@ -1,5 +1,6 @@
 """Test the HTML builder and check output against XPath."""
 
+import contextlib
 import os
 import posixpath
 import re
@@ -8,7 +9,7 @@ import pytest
 
 from sphinx.builders.html import validate_html_extra_path, validate_html_static_path
 from sphinx.deprecation import RemovedInSphinx80Warning
-from sphinx.errors import ConfigError
+from sphinx.errors import ConfigError, ThemeError
 from sphinx.util.console import strip_colors
 from sphinx.util.inventory import InventoryFile
 
@@ -16,6 +17,31 @@ from tests.test_builders.xpath_data import FIGURE_CAPTION
 from tests.test_builders.xpath_util import check_xpath
 
 
+def test_html_sidebars_error(make_app, tmp_path):
+    (tmp_path / 'conf.py').touch()
+    (tmp_path / 'index.rst').touch()
+    app = make_app(
+        buildername='html',
+        srcdir=tmp_path,
+        confoverrides={'html_sidebars': {'index': 'searchbox.html'}},
+    )
+
+    # Test that the error is logged
+    warnings = app.warning.getvalue()
+    assert ("ERROR: Values in 'html_sidebars' must be a list of strings. "
+            "At least one pattern has a string value: 'index'. "
+            "Change to `html_sidebars = {'index': ['searchbox.html']}`.") in warnings
+
+    # But that the value is unchanged.
+    # (Remove this bit of the test in Sphinx 8)
+    def _html_context_hook(app, pagename, templatename, context, doctree):
+        assert context["sidebars"] == 'searchbox.html'
+    app.connect('html-page-context', _html_context_hook)
+    with contextlib.suppress(ThemeError):
+        # ignore template rendering issues (ThemeError).
+        app.build()
+
+
 def test_html4_error(make_app, tmp_path):
     (tmp_path / 'conf.py').write_text('', encoding='utf-8')
     with pytest.raises(

{sphinx-7.4.4 → sphinx-7.4.6}/tests/test_builders/test_build_latex.py

@@ -158,21 +158,21 @@ def test_writer(app, status, warning):
 
     assert ('\\begin{wrapfigure}{r}{0pt}\n\\centering\n'
             '\\noindent\\sphinxincludegraphics{{rimg}.png}\n'
-            '\\caption{figure with align option}\\label{\\detokenize{markup:id9}}'
+            '\\caption{figure with align option}\\label{\\detokenize{markup:id10}}'
             '\\end{wrapfigure}\n\n'
             '\\mbox{}\\par\\vskip-\\dimexpr\\baselineskip+\\parskip\\relax' in result)
 
     assert ('\\begin{wrapfigure}{r}{0.500\\linewidth}\n\\centering\n'
             '\\noindent\\sphinxincludegraphics{{rimg}.png}\n'
             '\\caption{figure with align \\& figwidth option}'
-            '\\label{\\detokenize{markup:id10}}'
+            '\\label{\\detokenize{markup:id11}}'
             '\\end{wrapfigure}\n\n'
             '\\mbox{}\\par\\vskip-\\dimexpr\\baselineskip+\\parskip\\relax' in result)
 
     assert ('\\begin{wrapfigure}{r}{3cm}\n\\centering\n'
             '\\noindent\\sphinxincludegraphics[width=3cm]{{rimg}.png}\n'
             '\\caption{figure with align \\& width option}'
-            '\\label{\\detokenize{markup:id11}}'
+            '\\label{\\detokenize{markup:id12}}'
             '\\end{wrapfigure}\n\n'
             '\\mbox{}\\par\\vskip-\\dimexpr\\baselineskip+\\parskip\\relax' in result)
 
@@ -1591,7 +1591,9 @@ def test_latex_labels(app, status, warning):
 def test_latex_figure_in_admonition(app, status, warning):
     app.build(force_all=True)
     result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8')
-    assert r'\begin{figure}[H]' in result
+    assert 'tabulary' not in result
+    for type in ('caution', 'note', 'seealso', 'todo'):
+        assert f'{type} directive.\n\n\\begin{{figure}}[H]' in result
 
 
 def test_default_latex_documents():

{sphinx-7.4.4 → sphinx-7.4.6}/tests/test_extensions/test_ext_autosummary.py

@@ -506,12 +506,20 @@ def test_autosummary_recursive(app, status, warning):
 
     # Check content of recursively generated stub-files
     content = (app.srcdir / 'generated' / 'package.rst').read_text(encoding='utf8')
-    assert 'package.module' in content
-    assert 'package.package' in content
-    assert 'package.module_importfail' in content
+    assert 'module' in content
+    assert 'package' in content
+    assert 'module_importfail' in content
+    # we no longer generate fully-qualified module names.
+    assert 'package.module' not in content
+    assert 'package.package' not in content
+    assert 'package.module_importfail' not in content
 
     content = (app.srcdir / 'generated' / 'package.package.rst').read_text(encoding='utf8')
-    assert 'package.package.module' in content
+    assert 'module' in content
+    assert 'package.package.module' not in content
+
+    warnings = app.warning.getvalue()
+    assert 'Summarised items should not include the current module.' not in warnings
 
 
 @pytest.mark.sphinx('dummy', testroot='ext-autosummary-recursive',
@@ -599,11 +607,11 @@ def test_autosummary_imported_members(app, status, warning):
         assert ('   .. autosummary::\n'
                 '   \n'
                 '      Bar\n'
-                '   \n' in module)
+                '   ' in module)
         assert ('   .. autosummary::\n'
                 '   \n'
                 '      foo\n'
-                '   \n' in module)
+                '   ' in module)
     finally:
         sys.modules.pop('autosummary_dummy_package', None)
 
@@ -627,7 +635,7 @@ def test_autosummary_module_all(app, status, warning):
         assert ('.. autosummary::\n'
                 '   :toctree:\n'
                 '   :recursive:\n\n'
-                '   autosummary_dummy_package_all.extra_dummy_module\n\n' in module)
+                '   extra_dummy_module\n' in module)
     finally:
         sys.modules.pop('autosummary_dummy_package_all', None)
 

{sphinx-7.4.4 → sphinx-7.4.6}/tests/test_extensions/test_ext_autosummary_imports.py

@@ -38,3 +38,12 @@ def test_autosummary_import_cycle(app, warning):
         "Replace 'spam.eggs.Ham' with 'Ham'."
     )
     assert expected in app.warning.getvalue()
+
+
+@pytest.mark.sphinx('dummy', testroot='ext-autosummary-module_prefix')
+@pytest.mark.usefixtures("rollback_sysmodules")
+def test_autosummary_generate_prefixes(app, warning):
+    app.build()
+    warnings = app.warning.getvalue()
+    assert 'Summarised items should not include the current module.' not in warnings
+    assert warnings == ''

{sphinx-7.4.4 → sphinx-7.4.6}/tests/test_util/test_util_inventory.py

@@ -49,12 +49,22 @@ def test_read_inventory_v2_not_having_version():
         ('foo', '', '/util/foo.html#module-module1', 'Long Module desc')
 
 
-def test_ambiguous_definition_warning(warning):
+def test_ambiguous_definition_warning(warning, status):
     f = BytesIO(INVENTORY_V2_AMBIGUOUS_TERMS)
     InventoryFile.load(f, '/util', posixpath.join)
 
-    assert 'contains multiple definitions for std:term:a' not in warning.getvalue().lower()
-    assert 'contains multiple definitions for std:term:b' in warning.getvalue().lower()
+    def _multiple_defs_notice_for(entity: str) -> str:
+        return f'contains multiple definitions for {entity}'
+
+    # was warning-level; reduced to info-level - see https://github.com/sphinx-doc/sphinx/issues/12613
+    mult_defs_a, mult_defs_b = (
+        _multiple_defs_notice_for('std:term:a'),
+        _multiple_defs_notice_for('std:term:b'),
+    )
+    assert mult_defs_a not in warning.getvalue().lower()
+    assert mult_defs_a not in status.getvalue().lower()
+    assert mult_defs_b not in warning.getvalue().lower()
+    assert mult_defs_b in status.getvalue().lower()
 
 
 def _write_appconfig(dir, language, prefix=None):

sphinx-7.4.4/tests/roots/test-latex-figure-in-admonition/index.rst

@@ -1,9 +0,0 @@
-Test Figure in Admonition
-=========================
-
-.. caution::
-
-   This uses a figure in an admonition.
-
-   .. figure:: img.png
-

sphinx-7.4.4/tests/roots/test-toctree-maxdepth/conf.py

@@ -1 +0,0 @@
-exclude_patterns = ['_build']