Merge branch 'master' into admonition-collapsible

CHANGES.rst

@@ -31,7 +31,7 @@ Deprecated
 Features added
 --------------
 
-* Add a new ``duplicate_declaration`` warning type,
+* #13173: Add a new ``duplicate_declaration`` warning type,
   with ``duplicate_declaration.c`` and ``duplicate_declaration.cpp`` subtypes.
   Patch by Julien Lecomte and Adam Turner.
 * #11824: linkcode: Allow extensions to add support for a domain by defining
@@ -46,11 +46,11 @@ Features added
   Patch by Adam Turner.
 * #13065: Enable colour by default in when running on CI.
   Patch by Adam Turner.
-* Allow supressing warnings from the :rst:dir:`toctree` directive when a glob
-  pattern doesn't match any documents, via the new ``toc.glob_not_matching``
-  warning sub-type.
+* #13230: Allow supressing warnings from the :rst:dir:`toctree` directive
+  when a glob pattern doesn't match any documents,
+  via the new ``toc.empty_glob`` warning sub-type.
   Patch by Slawek Figiel.
-* #9732: Add the new ``autodoc.mock_objects`` warnings sub-type.
+* #9732: Add the new ``autodoc.mocked_object`` warnings sub-type.
   Patch by Cyril Roelandt.
 * #7630, #4824: autodoc: Use :file:`.pyi` type stub files
   to auto-document native modules.
@@ -70,6 +70,24 @@ Features added
   which defaults to ``True`` for backwards compatibility.
   The default will change to ``False`` in Sphinx 10.
   Patch by Adam Turner.
+* #9732: Add the new ``ref.any`` warnings sub-type
+  to allow suppressing the ambiguous 'any' cross-reference warning.
+  Patch by Simão Afonso and Adam Turner.
+* #13272: The Python and JavaScript module directives now support
+  the ``:no-index-entry:`` option.
+  Patch by Adam Turner.
+* #12233: autodoc: Allow directives to use ``:no-index-entry:``
+  and include the ``:no-index:`` and ``:no-index-entry:`` options within
+  :confval:`autodoc_default_options`.
+  Patch by Jonny Saunders and Adam Turner.
+* #13172: Add support for short signatures in autosummary.
+  Patch by Tim Hoffmann.
+* #13271: Change the signature prefix for abstract methods
+  in the Python domain to *abstractmethod* from *abstract*.
+  Patch by Adam Turner.
+* #13271: Support the ``:abstract:`` option for
+  classes, methods, and properties in the Python domain.
+  Patch by Adam Turner.
 * #12507: Add the :ref:`collapsible <collapsible-admonitions>` option to admonition directives.
   Patch by Chris Sewell.
 
@@ -83,8 +101,7 @@ Bugs fixed
 * #13130: LaTeX docs: ``pdflatex`` index creation may fail for index entries
   in French.  See :confval:`latex_use_xindy`.
   Patch by Jean-François B.
-* LaTeX: fix a ``7.4.0`` typo in a default for ``\sphinxboxsetup``
-  (refs: PR #13152).
+* #13152: LaTeX: fix a typo from v7.4.0 in a default for ``\sphinxboxsetup``.
   Patch by Jean-François B.
 * #13096: HTML Search: check that query terms exist as properties in
   term indices before accessing them.

doc/usage/configuration.rst

@@ -1384,6 +1384,7 @@ Options for warning control
    * ``misc.copy_overwrite``
    * ``misc.highlighting_failure``
    * ``ref.citation``
+   * ``ref.any``
    * ``ref.doc``
    * ``ref.footnote``
    * ``ref.keyword``
@@ -1487,6 +1488,9 @@ Options for warning control
    .. versionadded:: 8.2
       Added ``autodoc.mocked_object``
 
+   .. versionadded:: 8.2
+      Added ``ref.any``
+
 
 Builder options
 ===============

doc/usage/domains/index.rst

@@ -48,7 +48,7 @@ the content should be the description.
 
 A domain will typically keep an internal index of all entities to aid
 cross-referencing.
-Typically it will also add entries in the shown general index.
+Typically, it will also add entries in the shown general index.
 If you want to suppress the addition of an entry in the shown index, you can
 give the directive option flag ``:no-index-entry:``.
 If you want to exclude the object description from the table of contents, you

doc/usage/domains/python.rst

@@ -230,6 +230,20 @@ The following directives are provided for module and class contents:
 
    .. rubric:: options
 
+   .. rst:directive:option:: abstract
+      :type: no value
+
+      Indicate that the class is an abstract base class.
+      This produces the following output:
+
+      .. py:class:: Cheese
+         :no-index:
+         :abstract:
+
+         A cheesy representation.
+
+      .. versionadded:: 8.2
+
    .. rst:directive:option:: canonical
       :type: full qualified name including module name
 
@@ -320,10 +334,22 @@ The following directives are provided for module and class contents:
 
    .. rubric:: options
 
-   .. rst:directive:option:: abstractmethod
+   .. rst:directive:option:: abstract
+                             abstractmethod
       :type: no value
 
       Indicate the property is abstract.
+      This produces the following output:
+
+      .. py:property:: Cheese.amount_in_stock
+         :no-index:
+         :abstractmethod:
+
+         Cheese levels at the *National Cheese Emporium*.
+
+      .. versionchanged:: 8.2
+
+         The ``:abstract:`` alias is also supported.
 
    .. rst:directive:option:: classmethod
       :type: no value
@@ -412,12 +438,23 @@ The following directives are provided for module and class contents:
 
    .. rubric:: options
 
-   .. rst:directive:option:: abstractmethod
+   .. rst:directive:option:: abstract
+                             abstractmethod
       :type: no value
 
       Indicate the method is an abstract method.
+      This produces the following output:
+
+      .. py:method:: Cheese.order_more_stock
+         :no-index:
+         :abstractmethod:
+
+         Order more cheese (we're fresh out!).
 
       .. versionadded:: 2.1
+      .. versionchanged:: 8.2
+
+         The ``:abstract:`` alias is also supported.
 
    .. rst:directive:option:: async
       :type: no value

doc/usage/extensions/autodoc.rst

@@ -326,6 +326,15 @@ Automatically document modules
 
       .. versionadded:: 0.4
 
+   .. rst:directive:option:: no-index-entry
+      :type:
+
+      Do not generate an index entry for the documented module
+      or any auto-documented members.
+      Unlike ``:no-index:``, cross-references are still created.
+
+      .. versionadded:: 8.2
+
    .. rst:directive:option:: platform: platforms
       :type: comma separated list
 
@@ -578,6 +587,15 @@ Automatically document classes or exceptions
 
       .. versionadded:: 0.4
 
+   .. rst:directive:option:: no-index-entry
+      :type:
+
+      Do not generate an index entry for the documented class
+      or any auto-documented members.
+      Unlike ``:no-index:``, cross-references are still created.
+
+      .. versionadded:: 8.2
+
    .. rst:directive:option:: class-doc-from
       :type: class, init, or both
 
@@ -854,6 +872,14 @@ Automatically document function-like objects
 
       .. versionadded:: 0.4
 
+   .. rst:directive:option:: no-index-entry
+      :type:
+
+      Do not generate an index entry for the documented function.
+      Unlike ``:no-index:``, cross-references are still created.
+
+      .. versionadded:: 8.2
+
 
 Automatically document attributes or data
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -900,11 +926,18 @@ Automatically document attributes or data
    .. rst:directive:option:: no-index
       :type:
 
-      Do not generate an index entry for the documented class
-      or any auto-documented members.
+      Do not generate an index entry for the documented variable or constant.
 
       .. versionadded:: 0.4
 
+   .. rst:directive:option:: no-index-entry
+      :type:
+
+      Do not generate an index entry for the documented variable or constant.
+      Unlike ``:no-index:``, cross-references are still created.
+
+      .. versionadded:: 8.2
+
    .. rst:directive:option:: annotation: value
       :type: string
 
@@ -1039,6 +1072,8 @@ There are also config values that you can set:
    * ``'show-inheritance'``: See :rst:dir:`autoclass:show-inheritance`.
    * ``'class-doc-from'``: See :rst:dir:`autoclass:class-doc-from`.
    * ``'no-value'``: See :rst:dir:`autodata:no-value`.
+   * ``'no-index'``: See :rst:dir:`automodule:no-index`.
+   * ``'no-index-entry'``: See :rst:dir:`automodule:no-index-entry`.
 
    .. versionadded:: 1.8
 

doc/usage/extensions/autosummary.rst

@@ -102,18 +102,31 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
 
       .. versionadded:: 3.1
 
-   .. rst:directive:option:: no-signatures
+   .. rst:directive:option:: signatures: format
+
+      How to display signatures. Valid values are
+
+      - ``long`` (*default*): use a long signature. This is still cut off so that name
+        plus signature do not exceeed a certain length.
+      - ``short``: Function and class signatures are displayed as ``(…)`` if they have
+        arguments and as ``()`` if they don't have arguments.
+      - ``none``: do not show signatures.
+
+      .. versionadded:: 8.2
+
+   .. rst:directive:option:: nosignatures
 
       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 directive option is superseded by the more general ``:signatures: none``.
 
-         The previous name has been retained as an alias,
-         but will be deprecated and removed
+         It will be deprecated and removed
          in a future version of Sphinx.
 
    .. rst:directive:option:: template: filename

doc/usage/referencing.rst

@@ -254,6 +254,9 @@ The following role creates a cross-reference to a term in a
    If you use a term that's not explained in a glossary, you'll get a warning
    during build.
 
+   This role also supports :ref:`custom link text <xref-modifiers>` from the general
+   cross-reference syntax.
+
 
 .. _any-role: