Merge branch 'master' into autosummary-short-signature

# Conflicts:
#	doc/usage/extensions/autosummary.rst
#	sphinx/ext/autosummary/__init__.py

Author: timhoffm

CHANGES.rst

@@ -60,6 +60,16 @@ Features added
   :confval:`python_trailing_comma_in_multi_line_signatures` and
   :confval:`javascript_trailing_comma_in_multi_line_signatures`
   configuration options.
+* #13264: Rename the :rst:dir:`math` directive's ``nowrap``option
+  to :rst:dir:`no-wrap``,
+  and rename the :rst:dir:`autosummary` directive's ``nosignatures``option
+  to :rst:dir:`no-signatures``.
+  Patch by Adam Turner.
+* #13269: Added the option to disable the use of type comments in
+  via the new :confval:`autodoc_use_type_comments` option,
+  which defaults to ``True`` for backwards compatibility.
+  The default will change to ``False`` in Sphinx 10.
+  Patch by Adam Turner.
 
 Bugs fixed
 ----------
@@ -92,6 +102,8 @@ Bugs fixed
   methods and attributes.
   Patch by Bénédikt Tran.
 * #12975: Avoid rendering a trailing comma in C and C++ multi-line signatures.
+* #13178: autodoc: Fix resolution for ``pathlib`` types.
+  Patch by Adam Turner.
 
 Testing
 -------

doc/conf.py

@@ -187,9 +187,16 @@
     ('py:attr', 'srcline'),
     ('py:class', '_AutodocProcessDocstringListener'),
     ('py:class', '_ConfigRebuild'),  # sphinx.application.Sphinx.add_config_value
+    # sphinx.application.Sphinx.add_html_math_renderer
+    ('py:class', '_MathsBlockRenderers'),
+    # sphinx.application.Sphinx.add_html_math_renderer
+    ('py:class', '_MathsInlineRenderers'),
+    ('py:class', '_NodeHandler'),  # sphinx.application.Sphinx.add_enumerable_node
+    ('py:class', '_NodeHandlerPair'),  # sphinx.application.Sphinx.add_node
     ('py:class', '_StrPath'),  # sphinx.environment.BuildEnvironment.doc2path
     ('py:class', 'Element'),  # sphinx.domains.Domain
     ('py:class', 'Documenter'),  # sphinx.application.Sphinx.add_autodocumenter
+    ('py:class', 'Field'),  # sphinx.application.Sphinx.add_object_type
     ('py:class', 'IndexEntry'),  # sphinx.domains.IndexEntry
     ('py:class', 'Inliner'),  # sphinx.util.docutils.SphinxRole.inliner
     ('py:class', 'Lexer'),  # sphinx.application.Sphinx.add_lexer
@@ -200,10 +207,10 @@
     ('py:class', 'Path'),  # sphinx.application.Sphinx.connect
     ('py:class', 'RoleFunction'),  # sphinx.domains.Domain
     ('py:class', 'RSTState'),  # sphinx.utils.parsing.nested_parse_to_nodes
-    ('py:class', 'Theme'),  # sphinx.application.TemplateBridge
     ('py:class', 'SearchLanguage'),  # sphinx.application.Sphinx.add_search_language
     ('py:class', 'StringList'),  # sphinx.utils.parsing.nested_parse_to_nodes
     ('py:class', 'system_message'),  # sphinx.utils.docutils.SphinxDirective
+    ('py:class', 'Theme'),  # sphinx.application.TemplateBridge
     ('py:class', 'TitleGetter'),  # sphinx.domains.Domain
     ('py:class', 'todo_node'),  # sphinx.application.Sphinx.connect
     ('py:class', 'Transform'),  # sphinx.application.Sphinx.add_transform

doc/man/sphinx-apidoc.rst

@@ -103,12 +103,13 @@ Options
 
 .. option:: --implicit-namespaces
 
-   By default sphinx-apidoc processes sys.path searching for modules only.
-   Python 3.3 introduced :pep:`420` implicit namespaces that allow module path
-   structures such as ``foo/bar/module.py`` or ``foo/bar/baz/__init__.py``
-   (notice that ``bar`` and ``foo`` are namespaces, not modules).
+   Without this option, :program:`sphinx-apidoc` searches :data:`sys.path`
+   for Python packages containing :file:`__init__.py` files,
+   or single-file Python modules.
 
-   Interpret paths recursively according to PEP-0420.
+   This option instead uses :pep:`420` implicit namespaces that allow
+   layouts paths such as ``foo/bar/module.py`` or ``foo/bar/baz/__init__.py``
+   (note that ``bar`` and ``foo`` are namespaces, not modules).
 
 .. option:: -M, --module-first
 

doc/usage/domains/python.rst

@@ -135,11 +135,15 @@ The following directives are provided for module and class contents:
 
       This will be parsed as a Python expression for cross-referencing
       the type annotation.
-      As such, the argument to ``:type:`` should be a valid Python expression.
+      As such, the argument to ``:type:`` should be a valid `annotation expression`_.
 
-      .. caution:: The valid syntax for the ``:type:`` directive option
-                   differs from the syntax for the ``:type:`` `info field
-                   <info-field-lists_>`__.
+      .. caution::
+         The valid syntax for the ``:type:`` directive option differs from
+         the syntax for the ``:type:`` `info field <info-field-lists_>`__.
+         The ``:type:`` directive option does not understand
+         reStructuredText markup or the ``or`` or ``of`` keywords,
+         meaning unions must use ``|`` and sequences must use square brackets,
+         and roles such as ``:ref:`...``` cannot be used.
 
       .. versionadded:: 2.4
 
@@ -277,11 +281,15 @@ The following directives are provided for module and class contents:
 
       This will be parsed as a Python expression for cross-referencing
       the type annotation.
-      As such, the argument to ``:type:`` should be a valid Python expression.
+      As such, the argument to ``:type:`` should be a valid `annotation expression`_.
 
-      .. caution:: The valid syntax for the ``:type:`` directive option
-                   differs from the syntax for the ``:type:`` `info field
-                   <info-field-lists_>`__.
+      .. caution::
+         The valid syntax for the ``:type:`` directive option differs from
+         the syntax for the ``:type:`` `info field <info-field-lists_>`__.
+         The ``:type:`` directive option does not understand
+         reStructuredText markup or the ``or`` or ``of`` keywords,
+         meaning unions must use ``|`` and sequences must use square brackets,
+         and roles such as ``:ref:`...``` cannot be used.
 
       .. versionadded:: 2.4
 
@@ -329,11 +337,15 @@ The following directives are provided for module and class contents:
 
       This will be parsed as a Python expression for cross-referencing
       the type annotation.
-      As such, the argument to ``:type:`` should be a valid Python expression.
+      As such, the argument to ``:type:`` should be a valid `annotation expression`_.
 
-      .. caution:: The valid syntax for the ``:type:`` directive option
-                   differs from the syntax for the ``:type:`` `info field
-                   <info-field-lists_>`__.
+      .. caution::
+         The valid syntax for the ``:type:`` directive option differs from
+         the syntax for the ``:type:`` `info field <info-field-lists_>`__.
+         The ``:type:`` directive option does not understand
+         reStructuredText markup or the ``or`` or ``of`` keywords,
+         meaning unions must use ``|`` and sequences must use square brackets,
+         and roles such as ``:ref:`...``` cannot be used.
 
    .. rst::directive:option:: module
       :type: text
@@ -542,50 +554,66 @@ The following directives are provided for module and class contents:
 
    Refer to a decorator method using the :rst:role:`py:meth` role.
 
+.. _annotation expression: https://typing.readthedocs.io/en/latest/spec/annotations.html#type-and-annotation-expressions
+
 .. _signatures:
 
 Python Signatures
 -----------------
 
 Signatures of functions, methods and class constructors can be given like they
 would be written in Python.
+This can include default values, positional-only or keyword-only parameters,
+type annotations, and type parameters.
+For example:
+
+.. code-block:: rst
 
-Default values for optional arguments can be given (but if they contain commas,
-they will confuse the signature parser).  Python 3-style argument annotations
-can also be given as well as return type annotations::
+   .. py:function:: compile(source: str, filename: Path, symbol: str = 'file') -> ast.AST
 
-   .. py:function:: compile(source : string, filename, symbol='file') -> ast object
+.. py:function:: compile(source: str, filename: Path, symbol: str = 'file') -> ast.AST
+   :no-index:
 
 For functions with optional parameters that don't have default values
 (typically functions implemented in C extension modules without keyword
-argument support), you can use brackets to specify the optional parts:
+argument support),
+you can list multiple versions of the same signature in a single directive:
 
-.. py:function:: compile(source[, filename[, symbol]])
-   :no-contents-entry:
-   :no-index-entry:
+.. py:function:: compile(source)
+                 compile(source, filename)
+                 compile(source, filename, symbol)
+   :no-index:
+
+Another approach is to use square brackets to specify the optional parts.
+When using square brackets, it is customary to place
+the opening bracket before the comma (``[,``).
 
-It is customary to put the opening bracket before the comma.
+.. py:function:: compile(source[, filename[, symbol]])
+   :no-index:
 
 Python 3.12 introduced *type parameters*, which are type variables
-declared directly  within the class or function definition:
+declared directly within the class or function definition:
 
 .. code-block:: python
 
    class AnimalList[AnimalT](list[AnimalT]):
-      ...
+       ...
 
    def add[T](a: T, b: T) -> T:
-      return a + b
+       return a + b
 
-The corresponding reStructuredText documentation would be:
+The corresponding reStructuredText markup would be:
 
 .. code-block:: rst
 
    .. py:class:: AnimalList[AnimalT]
 
    .. py:function:: add[T](a: T, b: T) -> T
 
-See :pep:`695` and :pep:`696` for details and the full specification.
+.. seealso::
+
+   :pep:`695` and :pep:`696`, for details and the full specification.
+
 
 .. _info-field-lists:
 

doc/usage/extensions/autodoc.rst

@@ -1230,6 +1230,26 @@ There are also config values that you can set:
       Added as an experimental feature.  This will be integrated into autodoc core
       in the future.
 
+.. confval:: autodoc_use_type_comments
+   :type: :code-py:`bool`
+   :default: :code-py:`True`
+
+   Attempt to read ``# type: ...`` comments from source code
+   to supplement missing type annotations, if True.
+
+   This can be disabled if your source code does not use type comments,
+   for example if it exclusively uses type annotations or
+   does not use type hints of any kind.
+
+   .. versionadded:: 8.2
+
+      Added the option to disable the use of type comments in
+      via the new :confval:`!autodoc_use_type_comments` option,
+      which defaults to :code-py:`True` for backwards compatibility.
+      The default will change to :code-py:`False` in Sphinx 10.
+
+      .. xref RemovedInSphinx10Warning
+
 .. confval:: autodoc_warningiserror
    :type: :code-py:`bool`
    :default: :code-py:`True`

doc/usage/extensions/autosummary.rst

@@ -115,13 +115,22 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
       .. versionadded:: 8.2
 
    .. rst:directive:option:: nosignatures
+   .. rst:directive:option:: no-signatures
 
       Do not show function signatures in the summary.
 
       This is equivalent to ``:signatures: none``.
 
       .. versionadded:: 0.6
 
+      .. versionchanged:: 8.2
+
+         The directive option ``:nosignatures:`` was renamed to ``:no-signatures:``.
+
+         The previous name has been retained as an alias,
+         but will be deprecated and removed
+         in a future version of Sphinx.
+
    .. rst:directive:option:: template: filename
 
       Specify a custom template for rendering the summary.

doc/usage/extensions/intersphinx.rst

@@ -220,10 +220,12 @@ Showing all links of an Intersphinx mapping file
 ------------------------------------------------
 
 To show all Intersphinx links and their targets of an Intersphinx mapping file,
-run ``python -msphinx.ext.intersphinx url-or-path``.  This is helpful when
+run ``python -m sphinx.ext.intersphinx url-or-path``.  This is helpful when
 searching for the root cause of a broken Intersphinx link in a documentation
-project. The following example prints the Intersphinx mapping of the Python 3
-documentation::
+project.
+The following example prints the Intersphinx mapping of the Python documentation:
+
+.. code-block:: console
 
    $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv