Merge branch 'master' into typing-ext-overload

Author: AA-Turner

AUTHORS.rst

@@ -102,6 +102,7 @@ Contributors
 * Slawek Figiel -- additional warning suppression
 * Stefan Seefeld -- toctree improvements
 * Stefan van der Walt -- autosummary extension
+* Steve Piercy -- documentation improvements
 * \T. Powers -- HTML output improvements
 * Taku Shimizu -- epub3 builder
 * Thomas Lamb -- linkcheck builder

doc/extdev/markupapi.rst

@@ -173,9 +173,9 @@ The methods are used as follows:
       def run(self) -> list[Node]:
           container = docutils.nodes.Element()
           # either
-          nested_parse_with_titles(self.state, self.result, container)
+          nested_parse_with_titles(self.state, self.result, container, self.content_offset)
           # or
-          self.state.nested_parse(self.result, 0, container)
+          self.state.nested_parse(self.result, self.content_offset, container)
           parsed = container.children
           return parsed
 

doc/latex.rst

@@ -500,7 +500,7 @@ Keys that don't need to be overridden unless in special cases are:
    .. hint::
 
       If the key value is set to
-      :code-tex:`r'\\newcommand\sphinxbackoftitlepage{<Extra
+      :code-tex:`r'\\newcommand\\sphinxbackoftitlepage{<Extra
       material>}\\sphinxmaketitle'`, then ``<Extra material>`` will be
       typeset on back of title page (``'manual'`` docclass only).
 
@@ -1694,7 +1694,7 @@ Macros
   .. hint::
 
      If adding to preamble the loading of ``tocloft`` package, also add to
-     preamble :code-tex:`\\renewcommand\sphinxtableofcontentshook{}` else it
+     preamble :code-tex:`\\renewcommand\\sphinxtableofcontentshook{}` else it
      will reset :code-tex:`\\l@section` and :code-tex:`\\l@subsection`
      cancelling ``tocloft`` customization.
 

doc/man/sphinx-build.rst

@@ -272,13 +272,13 @@ Options
    From Sphinx 8.1, :option:`!--keep-going` is always enabled.
    Previously, it was only applicable whilst using :option:`--fail-on-warning`,
    which by default exited :program:`sphinx-build` on the first warning.
-   Using :option:`!--keep-going` runs :program:`!sphinx-build` to completion
+   Using :option:`!--keep-going` runs :program:`sphinx-build` to completion
    and exits with exit status 1 if errors are encountered.
 
    .. versionadded:: 1.8
    .. versionchanged:: 8.1
       :program:`sphinx-build` no longer exits on the first warning,
-      meaning that in effect :option:`!--fail-on-warning` is always enabled.
+      meaning that in effect :option:`!--keep-going` is always enabled.
       The option is retained for compatibility, but may be removed at some
       later date.
 

doc/usage/configuration.rst

@@ -3668,7 +3668,7 @@ and which failures and redirects it ignores.
    .. versionadded:: 4.1
 
    .. versionchanged:: 8.3
-      Setting :confval:`!linkcheck_allowed_redirects` to the empty directory
+      Setting :confval:`!linkcheck_allowed_redirects` to an empty dictionary
       may now be used to warn on all redirects encountered
       by the *linkcheck* builder.
 

pyproject.toml

@@ -92,7 +92,7 @@ docs = [
     "sphinxcontrib-websupport",
 ]
 lint = [
-    "ruff==0.11.7",
+    "ruff==0.11.9",
     "mypy==1.15.0",
     "sphinx-lint>=0.9",
     "types-colorama==0.4.15.20240311",
@@ -135,7 +135,7 @@ docs = [
     "sphinxcontrib-websupport",
 ]
 lint = [
-    "ruff==0.11.7",
+    "ruff==0.11.9",
     "sphinx-lint>=0.9",
 ]
 package = [
@@ -290,7 +290,6 @@ module = [
     "tests.test_util.test_util",
     "tests.test_util.test_util_display",
     "tests.test_util.test_util_docutils",
-    "tests.test_util.test_util_images",
     "tests.test_util.test_util_inventory",
     # tests/test_writers
     "tests.test_writers.test_docutilsconf",

sphinx/directives/other.py

@@ -5,6 +5,7 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, cast
 
+import docutils
 from docutils import nodes
 from docutils.parsers.rst import directives
 from docutils.parsers.rst.directives.misc import Class
@@ -21,14 +22,15 @@
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
-    from typing import Any, ClassVar
+    from typing import Any, ClassVar, Final
 
     from docutils.nodes import Element, Node
 
     from sphinx.application import Sphinx
     from sphinx.util.typing import ExtensionMetadata, OptionSpec
 
 
+DU_22_PLUS: Final = docutils.__version_info__ >= (0, 22, 0, 'alpha', 0)
 glob_re = re.compile(r'.*[*?\[].*')
 logger = logging.getLogger(__name__)
 
@@ -330,6 +332,14 @@ def run(self) -> list[Node]:
         surrounding_section_level = memo.section_level
         memo.title_styles = []
         memo.section_level = 0
+        if DU_22_PLUS:
+            # https://github.com/sphinx-doc/sphinx/issues/13539
+            # https://sourceforge.net/p/docutils/code/10093/
+            # https://sourceforge.net/p/docutils/patches/213/
+            surrounding_section_parents = memo.section_parents
+            memo.section_parents = []
+        else:
+            surrounding_section_parents = []
         try:
             self.state.nested_parse(
                 self.content, self.content_offset, node, match_titles=True
@@ -365,6 +375,8 @@ def run(self) -> list[Node]:
             return []
         finally:
             memo.title_styles = surrounding_title_styles
+            if DU_22_PLUS:
+                memo.section_parents = surrounding_section_parents
             memo.section_level = surrounding_section_level
 
 

sphinx/domains/javascript.py

@@ -137,8 +137,9 @@ def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]
                 _pseudo_parse_arglist(
                     signode,
                     arglist,
-                    multi_line_parameter_list,
-                    trailing_comma,
+                    multi_line_parameter_list=multi_line_parameter_list,
+                    trailing_comma=trailing_comma,
+                    env=self.env,
                 )
         return fullname, prefix
 

sphinx/domains/python/_annotations.py

@@ -552,15 +552,18 @@ def _keyword_only_separator() -> addnodes.desc_parameter:
 def _pseudo_parse_arglist(
     signode: desc_signature,
     arglist: str,
+    *,
     multi_line_parameter_list: bool = False,
     trailing_comma: bool = True,
+    env: BuildEnvironment,
 ) -> None:
     """'Parse' a list of arguments separated by commas.
 
     Arguments can have "optional" annotations given by enclosing them in
     brackets.  Currently, this will split at any comma, even if it's inside a
     string literal (e.g. default argument value).
     """
+    # TODO: decompose 'env' parameter into only the required bits
     paramlist = addnodes.desc_parameterlist()
     paramlist['multi_line_parameter_list'] = multi_line_parameter_list
     paramlist['multi_line_trailing_comma'] = trailing_comma
@@ -583,9 +586,30 @@ def _pseudo_parse_arglist(
                 ends_open += 1
                 argument = argument[:-1].strip()
             if argument:
-                stack[-1] += addnodes.desc_parameter(
-                    '', '', addnodes.desc_sig_name(argument, argument)
-                )
+                param_with_annotation, _, default_value = argument.partition('=')
+                param_name, _, annotation = param_with_annotation.partition(':')
+                del param_with_annotation
+
+                node = addnodes.desc_parameter()
+                node += addnodes.desc_sig_name('', param_name.strip())
+                if annotation:
+                    children = _parse_annotation(annotation.strip(), env=env)
+                    node += addnodes.desc_sig_punctuation('', ':')
+                    node += addnodes.desc_sig_space()
+                    node += addnodes.desc_sig_name('', '', *children)  # type: ignore[arg-type]
+                if default_value:
+                    if annotation:
+                        node += addnodes.desc_sig_space()
+                    node += addnodes.desc_sig_operator('', '=')
+                    if annotation:
+                        node += addnodes.desc_sig_space()
+                    node += nodes.inline(
+                        '',
+                        default_value.strip(),
+                        classes=['default_value'],
+                        support_smartquotes=False,
+                    )
+                stack[-1] += node
             while ends_open:
                 stack.append(addnodes.desc_optional())
                 stack[-2] += stack[-1]

sphinx/domains/python/_object.py

@@ -363,8 +363,9 @@ def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]
                 _pseudo_parse_arglist(
                     signode,
                     arglist,
-                    multi_line_parameter_list,
-                    trailing_comma,
+                    multi_line_parameter_list=multi_line_parameter_list,
+                    trailing_comma=trailing_comma,
+                    env=self.env,
                 )
             except (NotImplementedError, ValueError) as exc:
                 # duplicated parameter names raise ValueError and not a SyntaxError
@@ -374,8 +375,9 @@ def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]
                 _pseudo_parse_arglist(
                     signode,
                     arglist,
-                    multi_line_parameter_list,
-                    trailing_comma,
+                    multi_line_parameter_list=multi_line_parameter_list,
+                    trailing_comma=trailing_comma,
+                    env=self.env,
                 )
         else:
             if self.needs_arglist():

sphinx/util/parsing.py

@@ -5,15 +5,19 @@
 import contextlib
 from typing import TYPE_CHECKING
 
+import docutils
 from docutils.nodes import Element
 from docutils.statemachine import StringList, string2lines
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
+    from typing import Final
 
     from docutils.nodes import Node
     from docutils.parsers.rst.states import RSTState
 
+DU_22_PLUS: Final = docutils.__version_info__ >= (0, 22, 0, 'alpha', 0)
+
 
 def nested_parse_to_nodes(
     state: RSTState,
@@ -75,15 +79,23 @@ def _fresh_title_style_context(state: RSTState) -> Iterator[None]:
     memo = state.memo
     surrounding_title_styles: list[str | tuple[str, str]] = memo.title_styles
     surrounding_section_level: int = memo.section_level
+    if DU_22_PLUS:
+        surrounding_section_parents = memo.section_parents
+    else:
+        surrounding_section_parents = []
     # clear current title styles
     memo.title_styles = []
     memo.section_level = 0
+    if DU_22_PLUS:
+        memo.section_parents = []
     try:
         yield
     finally:
         # reset title styles
         memo.title_styles = surrounding_title_styles
         memo.section_level = surrounding_section_level
+        if DU_22_PLUS:
+            memo.section_parents = surrounding_section_parents
 
 
 def _text_to_string_list(

tests/roots/test-ext-autodoc/target/need_mocks.py

@@ -1,10 +1,9 @@
 import missing_module
 import missing_package1.missing_module1
+import sphinx.missing_module4
 from missing_module import missing_name
 from missing_package2 import missing_module2
 from missing_package3.missing_module3 import missing_name  # NoQA: F811
-
-import sphinx.missing_module4
 from sphinx.missing_module4 import missing_name2
 
 

tests/test_builders/test_build_linkcheck.py

@@ -1127,6 +1127,12 @@ def test_too_many_requests_retry_after_HTTP_date(tz, app, monkeypatch, capsys):
         ) as address:
             app.build()
 
+    # Undo side-effects: the monkeypatch context manager clears the TZ environment
+    # variable, but we also need to reset Python's internal notion of the current
+    # timezone.
+    if sys.platform != 'win32':
+        time.tzset()
+
     content = (app.outdir / 'output.json').read_text(encoding='utf8')
     assert json.loads(content) == {
         'filename': 'index.rst',

tests/test_domains/test_domain_py.py

@@ -38,20 +38,25 @@
 from sphinx.testing.util import assert_node
 from sphinx.writers.text import STDINDENT
 
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.environment import BuildEnvironment
 
-def parse(sig):
+
+def parse(sig: str, *, env: BuildEnvironment) -> str:
     m = py_sig_re.match(sig)
     if m is None:
         raise ValueError
     _name_prefix, _tp_list, _name, arglist, _retann = m.groups()
     signode = addnodes.desc_signature(sig, '')
-    _pseudo_parse_arglist(signode, arglist)
+    _pseudo_parse_arglist(signode, arglist, env=env)
     return signode.astext()
 
 
-def test_function_signatures() -> None:
-    rv = parse("compile(source : string, filename, symbol='file')")
-    assert rv == "(source : string, filename, symbol='file')"
+def test_function_signatures(app: Sphinx) -> None:
+    rv = parse("compile(source : string, filename, symbol='file')", env=app.env)
+    assert rv == "(source: string, filename, symbol='file')"
 
     for params, expect in [
         ('(a=1)', '(a=1)'),
@@ -60,17 +65,17 @@ def test_function_signatures() -> None:
         ('(a=1[, b=None])', '(a=1, [b=None])'),
         ('(a=[], [b=None])', '(a=[], [b=None])'),
         ('(a=[][, b=None])', '(a=[], [b=None])'),
-        ('(a: Foo[Bar]=[][, b=None])', '(a: Foo[Bar]=[], [b=None])'),
+        ('(a: Foo[Bar]=[][, b=None])', '(a: Foo[Bar] = [], [b=None])'),
     ]:
-        rv = parse(f'func{params}')
+        rv = parse(f'func{params}', env=app.env)
         assert rv == expect
 
         # Note: 'def f[Foo[Bar]]()' is not valid Python but people might write
         # it in a reST document to convene the intent of a higher-kinded type
         # variable.
         for tparams in ['', '[Foo]', '[Foo[Bar]]']:
             for retann in ['', '-> Foo', '-> Foo[Bar]', '-> anything else']:
-                rv = parse(f'func{tparams}{params} {retann}'.rstrip())
+                rv = parse(f'func{tparams}{params} {retann}'.rstrip(), env=app.env)
                 assert rv == expect