Merge branch 'master' into use-anchor-for-search-previews

CHANGES.rst

@@ -27,6 +27,9 @@ Features added
 * #11892: Improved performance when resolving cross references in cpp domain.
   Patch by Rouslan Korneychuk.
 
+* #11981: Improve rendering of signatures using ``slice`` syntax,
+  e.g., ``def foo(arg: np.float64[:,:]) -> None: ...``.
+
 Bugs fixed
 ----------
 
@@ -77,6 +80,8 @@ Bugs fixed
 * #11925: Blacklist the ``sphinxprettysearchresults`` extension; the functionality
   it provides was merged into Sphinx v2.0.0.
   Patch by James Addison.
+* #11962: Fix target resolution when using ``:paramtype:`` fields.
+  Patch by Bénédikt Tran.
 
 Testing
 -------

EXAMPLES.rst

@@ -66,7 +66,7 @@ Documentation using the classic theme
 * `EZ-Draw <https://pageperso.lis-lab.fr/~edouard.thiel/ez-draw/doc/en/html/ez-manual.html>`__ (customized)
 * `Generic Mapping Tools (GMT) <https://gmt.soest.hawaii.edu/doc/latest/>`__ (customized)
 * `Genomedata <https://noble.gs.washington.edu/proj/genomedata/doc/1.3.3/>`__
-* `GetFEM++ <https://getfem.org/>`__ (customized)
+* `GetFEM <https://getfem.org/>`__ (customized)
 * `Glasgow Haskell Compiler <https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/>`__ (customized)
 * `Grok <https://web.archive.org/web/20230708190705/http://grok.zope.org/doc/current/>`__ (customized)
 * `GROMACS <https://manual.gromacs.org/documentation/>`__
@@ -132,7 +132,6 @@ Documentation using the nature theme
 * `libLAS <https://liblas.org/>`__ (customized)
 * `Lmod <https://lmod.readthedocs.io/>`__
 * `MapServer <https://mapserver.org/>`__ (customized)
-* `pyglet <https://pyglet.readthedocs.io/>`__ (customized)
 * `PyWavelets <https://pywavelets.readthedocs.io/>`__
 * `Setuptools <https://setuptools.readthedocs.io/>`__
 * `Spring Python <https://docs.spring.io/spring-python/1.2.x/sphinx/html/>`__
@@ -253,6 +252,7 @@ Documentation using sphinx_rtd_theme
 * `PROS <https://pros.cs.purdue.edu/v5/>`__ (customized)
 * `Pweave <https://mpastell.com/pweave/>`__
 * `pyca/cryptograhpy <https://cryptography.io/>`__
+* `pyglet <https://pyglet.readthedocs.io/>`__
 * `PyNaCl <https://pynacl.readthedocs.io/>`__
 * `pyOpenSSL <https://www.pyopenssl.org/>`__
 * `PyPy <https://doc.pypy.org/>`__

doc/usage/restructuredtext/roles.rst

@@ -240,7 +240,10 @@ different style:
    :rst:role:`code` role instead.
 
    .. versionchanged:: 1.8
-      Allowed to escape curly braces with backslash
+      Allowed to escape curly braces with double backslash.  For example, in
+      ``:samp:`print(f"answer=\\{1+{variable}*2\\}")```, the part ``variable``
+      would be emphasized and the escaped curly braces would be displayed:
+      :samp:`print(f"answer=\\{1+{variable}*2\\}")`
 
 There is also an :rst:role:`index` role to generate index entries.
 
@@ -273,7 +276,7 @@ the standard reST markup for that purpose.
 Substitutions
 -------------
 
-The documentation system provides three substitutions that are defined by
+The documentation system provides some substitutions that are defined by
 default. They are set in the build configuration file.
 
 .. describe:: |release|

sphinx/environment/__init__.py

@@ -81,9 +81,7 @@
 
 if TYPE_CHECKING:
     from collections.abc import MutableMapping
-    from typing import Literal
-
-    from typing_extensions import overload
+    from typing import Literal, overload
 
     from sphinx.domains.c import CDomain
     from sphinx.domains.changeset import ChangeSetDomain

sphinx/ext/napoleon/__init__.py

@@ -339,7 +339,7 @@ def _patch_python_domain() -> None:
     PyObject.doc_field_types.append(
         PyTypedField('keyword', label=_('Keyword Arguments'),
                      names=('keyword', 'kwarg', 'kwparam'),
-                     typerolename='obj', typenames=('paramtype', 'kwtype'),
+                     typerolename='class', typenames=('paramtype', 'kwtype'),
                      can_collapse=True))
 
 

sphinx/pycode/ast.py

@@ -156,6 +156,20 @@ def visit_Name(self, node: ast.Name) -> str:
     def visit_Set(self, node: ast.Set) -> str:
         return "{" + ", ".join(self.visit(e) for e in node.elts) + "}"
 
+    def visit_Slice(self, node: ast.Slice) -> str:
+        if not node.lower and not node.upper and not node.step:
+            # Empty slice with default values -> [:]
+            return ":"
+
+        start = self.visit(node.lower) if node.lower else ""
+        stop = self.visit(node.upper) if node.upper else ""
+        if not node.step:
+            # Default step size -> [start:stop]
+            return f"{start}:{stop}"
+
+        step = self.visit(node.step) if node.step else ""
+        return f"{start}:{stop}:{step}"
+
     def visit_Subscript(self, node: ast.Subscript) -> str:
         def is_simple_tuple(value: ast.expr) -> bool:
             return (

sphinx/search/__init__.py

@@ -377,7 +377,7 @@ def get_terms(self, fn2index: dict[str, int]) -> tuple[dict[str, list[int] | int
                     if fn in fn2index:
                         rv[k] = fn2index[fn]
                 else:
-                    rv[k] = sorted([fn2index[fn] for fn in v if fn in fn2index])
+                    rv[k] = sorted(fn2index[fn] for fn in v if fn in fn2index)
         return rvs
 
     def freeze(self) -> dict[str, Any]:

sphinx/util/inspect.py

@@ -400,7 +400,7 @@ def object_description(obj: Any, *, _seen: frozenset = frozenset()) -> str:
         if id(obj) in seen:
             return 'tuple(...)'
         seen |= frozenset([id(obj)])
-        return '(%s%s)' % (
+        return '({}{})'.format(
             ', '.join(object_description(x, _seen=seen) for x in obj),
             ',' * (len(obj) == 1),
         )

sphinx/writers/html5.py

@@ -247,8 +247,8 @@ def depart_desc_type_parameter(self, node: Element) -> None:
         self.depart_desc_parameter(node)
 
     def visit_desc_optional(self, node: Element) -> None:
-        self.params_left_at_level = sum([isinstance(c, addnodes.desc_parameter)
-                                         for c in node.children])
+        self.params_left_at_level = sum(isinstance(c, addnodes.desc_parameter)
+                                        for c in node.children)
         self.optional_param_level += 1
         self.max_optional_param_level = self.optional_param_level
         if self.multi_line_parameter_list:

sphinx/writers/latex.py

@@ -911,8 +911,8 @@ def depart_desc_type_parameter(self, node: Element) -> None:
         self._depart_sig_parameter(node)
 
     def visit_desc_optional(self, node: Element) -> None:
-        self.params_left_at_level = sum([isinstance(c, addnodes.desc_parameter)
-                                         for c in node.children])
+        self.params_left_at_level = sum(isinstance(c, addnodes.desc_parameter)
+                                        for c in node.children)
         self.optional_param_level += 1
         self.max_optional_param_level = self.optional_param_level
         if self.multi_line_parameter_list:

sphinx/writers/text.py

@@ -685,8 +685,8 @@ def visit_desc_type_parameter(self, node: Element) -> None:
         self.visit_desc_parameter(node)
 
     def visit_desc_optional(self, node: Element) -> None:
-        self.params_left_at_level = sum([isinstance(c, addnodes.desc_parameter)
-                                         for c in node.children])
+        self.params_left_at_level = sum(isinstance(c, addnodes.desc_parameter)
+                                        for c in node.children)
         self.optional_param_level += 1
         self.max_optional_param_level = self.optional_param_level
         if self.multi_line_parameter_list:

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

@@ -17,3 +17,6 @@ async def asyncgenerator():
 
 builtin_func = print
 partial_builtin_func = partial(print)
+
+def slice_arg_func(arg: 'float64[:, :]'):
+    pass

tests/roots/test-ext-napoleon-paramtype/conf.py

@@ -0,0 +1,15 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('.'))
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.intersphinx'
+]
+
+# Python inventory is manually created in the test
+# in order to avoid creating a real HTTP connection
+intersphinx_mapping = {}
+intersphinx_cache_limit = 0
+intersphinx_disabled_reftypes = []

tests/roots/test-ext-napoleon-paramtype/index.rst

@@ -0,0 +1,8 @@
+test-ext-napoleon
+=================
+
+.. automodule:: pkg.bar
+   :members:
+
+.. automodule:: pkg.foo
+   :members:

tests/roots/test-ext-napoleon-paramtype/pkg/bar.py

@@ -0,0 +1,10 @@
+class Bar:
+    """The bar."""
+    def list(self) -> None:
+        """A list method."""
+
+    @staticmethod
+    def int() -> float:
+        """An int method."""
+        return 1.0
+

tests/roots/test-ext-napoleon-paramtype/pkg/foo.py

@@ -0,0 +1,27 @@
+class Foo:
+    """The foo."""
+    def do(
+        self,
+        *,
+        keyword_paramtype,
+        keyword_kwtype,
+        kwarg_paramtype,
+        kwarg_kwtype,
+        kwparam_paramtype,
+        kwparam_kwtype,
+    ):
+        """Some method.
+
+        :keyword keyword_paramtype: some param
+        :paramtype keyword_paramtype: list[int]
+        :keyword keyword_kwtype: some param
+        :kwtype keyword_kwtype: list[int]
+        :kwarg kwarg_paramtype: some param
+        :paramtype kwarg_paramtype: list[int]
+        :kwarg kwarg_kwtype: some param
+        :kwtype kwarg_kwtype: list[int]
+        :kwparam kwparam_paramtype: some param
+        :paramtype kwparam_paramtype: list[int]
+        :kwparam kwparam_kwtype: some param
+        :kwtype kwparam_kwtype: list[int]
+        """

tests/roots/test-manpage_url/index.rst

@@ -1,5 +1,7 @@
- * :manpage:`man(1)`
- * :manpage:`ls.1`
- * :manpage:`sphinx`
- * :manpage:`mailx(1) <bsd-mailx/mailx.1>`
- * :manpage:`!man(1)`
+The :manpage:`cp(1)`
+--------------------
+* :manpage:`man(1)`
+* :manpage:`ls.1`
+* :manpage:`sphinx`
+* :manpage:`mailx(1) <bsd-mailx/mailx.1>`
+* :manpage:`!man(1)`

tests/test_builders/test_build_html.py

@@ -293,6 +293,20 @@ def test_html_sidebar(app, status, warning):
     assert ctx['sidebars'] == []
 
 
+@pytest.mark.parametrize(("fname", "expect"), [
+    ('index.html', (".//h1/em/a[@href='https://example.com/cp.1']", '', True)),
+    ('index.html', (".//em/a[@href='https://example.com/man.1']", '', True)),
+    ('index.html', (".//em/a[@href='https://example.com/ls.1']", '', True)),
+    ('index.html', (".//em/a[@href='https://example.com/sphinx.']", '', True)),
+])
+@pytest.mark.sphinx('html', testroot='manpage_url', confoverrides={
+    'manpages_url': 'https://example.com/{page}.{section}'})
+@pytest.mark.test_params(shared_result='test_build_html_manpage_url')
+def test_html_manpage(app, cached_etree_parse, fname, expect):
+    app.build()
+    check_xpath(cached_etree_parse(app.outdir / fname), fname, *expect)
+
+
 @pytest.mark.sphinx('html', testroot='toctree-glob',
                     confoverrides={'html_baseurl': 'https://example.com/'})
 def test_html_baseurl(app, status, warning):

tests/test_extensions/test_ext_autodoc_autofunction.py

@@ -199,3 +199,14 @@ def test_async_generator(app):
         '   :async:',
         '',
     ]
+
+
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_slice_function_arg(app):
+    actual = do_autodoc(app, 'function', 'target.functions.slice_arg_func')
+    assert list(actual) == [
+        '',
+        '.. py:function:: slice_arg_func(arg: float64[:, :])',
+        '   :module: target.functions',
+        '',
+    ]

tests/test_extensions/test_ext_napoleon_docstring.py

@@ -1,13 +1,17 @@
 """Tests for :mod:`sphinx.ext.napoleon.docstring` module."""
 
 import re
+import zlib
 from collections import namedtuple
 from inspect import cleandoc
+from itertools import product
 from textwrap import dedent
 from unittest import mock
 
 import pytest
+from html5lib import HTMLParser
 
+from sphinx.ext.intersphinx import load_mappings, normalize_intersphinx_mapping
 from sphinx.ext.napoleon import Config
 from sphinx.ext.napoleon.docstring import (
     GoogleDocstring,
@@ -2659,3 +2663,42 @@ def test_napoleon_and_autodoc_typehints_description_documented_params(app, statu
         '\n'
         '      * ****kwargs** (*int*) -- Extra arguments.\n'
     )
+
+
+@pytest.mark.sphinx('html', testroot='ext-napoleon-paramtype', freshenv=True)
+def test_napoleon_keyword_and_paramtype(app, tmp_path):
+    inv_file = tmp_path / 'objects.inv'
+    inv_file.write_bytes(b'''\
+# Sphinx inventory version 2
+# Project: Intersphinx Test
+# Version: 42
+# The remainder of this file is compressed using zlib.
+''' + zlib.compress(b'''\
+None py:data 1 none.html -
+list py:class 1 list.html -
+int py:class 1 int.html -
+'''))  # NoQA: W291
+    app.config.intersphinx_mapping = {'python': ('127.0.0.1:5555', str(inv_file))}
+    normalize_intersphinx_mapping(app, app.config)
+    load_mappings(app)
+
+    app.build(force_all=True)
+
+    buffer = (app.outdir / 'index.html').read_bytes()
+    etree = HTMLParser(namespaceHTMLElements=False).parse(buffer)
+
+    for name, typename in product(('keyword', 'kwarg', 'kwparam'), ('paramtype', 'kwtype')):
+        param = f'{name}_{typename}'
+        li_ = list(etree.findall(f'.//li/p/strong[.="{param}"]/../..'))
+        assert len(li_) == 1
+        li = li_[0]
+
+        text = li.text or ''.join(li.itertext())
+        assert text == f'{param} (list[int]) \u2013 some param'
+
+        a_ = list(li.findall('.//a[@class="reference external"]'))
+
+        assert len(a_) == 2
+        for a, uri in zip(a_, ('list.html', 'int.html')):
+            assert a.attrib['href'] == f'127.0.0.1:5555/{uri}'
+            assert a.attrib['title'] == '(in Intersphinx Test v42)'