Merging upstream version 7.4.7.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

7 files changed, 114 insertions, 17 deletions

diff --git a/doc/usage/domains/c.rst b/doc/usage/domains/c.rst
index 3c1a41d..49aa5ca 100644
--- a/doc/usage/domains/c.rst
+++ b/doc/usage/domains/c.rst
@@ -24,7 +24,7 @@ The C domain (name **c**) is suited for documentation of C API.
       .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
 
    Note that you don't have to backslash-escape asterisks in the signature, as
-   it is not parsed by the reST inliner.
+   it is not parsed by the reStructuredText inliner.
 
    In the description of a function you can use the following info fields
    (see also :ref:`info-field-lists`).
@@ -128,7 +128,7 @@ The C domain (name **c**) is suited for documentation of C API.
    Describes a C type, either as a typedef, or the alias for an unspecified
    type.
 
-.. _c-roles:
+.. _c-xref-roles:
 
 Cross-referencing C constructs
 ------------------------------
diff --git a/doc/usage/domains/cpp.rst b/doc/usage/domains/cpp.rst
index 6c9372b..57cb932 100644
--- a/doc/usage/domains/cpp.rst
+++ b/doc/usage/domains/cpp.rst
@@ -568,7 +568,7 @@ following fields:
 .. versionadded:: 4.3
    The ``retval`` field type.
 
-.. _cpp-roles:
+.. _cpp-xref-roles:
 
 Cross-referencing
 -----------------
diff --git a/doc/usage/domains/index.rst b/doc/usage/domains/index.rst
index b5d43ce..8c47134 100644
--- a/doc/usage/domains/index.rst
+++ b/doc/usage/domains/index.rst
@@ -1,5 +1,7 @@
 .. highlight:: rst
 
+.. _usage-domains:
+
 =======
 Domains
 =======
@@ -121,7 +123,7 @@ This is particularly useful for literate programming:
    .. py:function:: spam(eggs)
       :no-typesetting:
 
-   .. code::
+   .. code:: python
 
       def spam(eggs):
           pass
diff --git a/doc/usage/domains/javascript.rst b/doc/usage/domains/javascript.rst
index 630b52e..ba0ff10 100644
--- a/doc/usage/domains/javascript.rst
+++ b/doc/usage/domains/javascript.rst
@@ -120,7 +120,7 @@ The JavaScript domain (name **js**) provides the following directives:
 
    Describes the attribute *name* of *object*.
 
-.. _js-roles:
+.. _js-xref-roles:
 
 These roles are provided to refer to the described objects:
 
diff --git a/doc/usage/domains/python.rst b/doc/usage/domains/python.rst
index 96982f1..5b98baa 100644
--- a/doc/usage/domains/python.rst
+++ b/doc/usage/domains/python.rst
@@ -124,8 +124,9 @@ The following directives are provided for module and class contents:
 .. rst:directive:: .. py:data:: name
 
    Describes global data in a module, including both variables and values used
-   as "defined constants."  Class and object attributes are not documented
-   using this environment.
+   as "defined constants."
+   Consider using :rst:dir:`py:type` for type aliases instead
+   and :rst:dir:`py:attribute` for class variables and instance attributes.
 
    .. rubric:: options
 
@@ -259,6 +260,7 @@ The following directives are provided for module and class contents:
    Describes an object data attribute.  The description should include
    information about the type of the data to be expected and whether it may be
    changed directly.
+   Type aliases should be documented with :rst:dir:`py:type`.
 
    .. rubric:: options
 
@@ -315,6 +317,55 @@ The following directives are provided for module and class contents:
       Describe the location where the object is defined.  The default value is
       the module specified by :rst:dir:`py:currentmodule`.
 
+.. rst:directive:: .. py:type:: name
+
+   Describe a :ref:`type alias <python:type-aliases>`.
+
+   The type that the alias represents should be described
+   with the :rst:dir:`!canonical` option.
+   This directive supports an optional description body.
+
+   For example:
+
+   .. code-block:: rst
+
+      .. py:type:: UInt64
+
+         Represent a 64-bit positive integer.
+
+   will be rendered as follows:
+
+   .. py:type:: UInt64
+      :no-contents-entry:
+      :no-index-entry:
+
+      Represent a 64-bit positive integer.
+
+   .. rubric:: options
+
+   .. rst:directive:option:: canonical
+      :type: text
+
+      The canonical type represented by this alias, for example:
+
+      .. code-block:: rst
+
+         .. py:type:: StrPattern
+            :canonical: str | re.Pattern[str]
+
+            Represent a regular expression or a compiled pattern.
+
+      This is rendered as:
+
+      .. py:type:: StrPattern
+         :no-contents-entry:
+         :no-index-entry:
+         :canonical: str | re.Pattern[str]
+
+         Represent a regular expression or a compiled pattern.
+
+   .. versionadded:: 7.4
+
 .. rst:directive:: .. py:method:: name(parameters)
                    .. py:method:: name[type parameters](parameters)
 
@@ -494,7 +545,7 @@ It is customary to put the opening bracket before the comma.
 Python 3.12 introduced *type parameters*, which are type variables
 declared directly  within the class or function definition:
 
-.. code:: python
+.. code-block:: python
 
    class AnimalList[AnimalT](list[AnimalT]):
       ...
@@ -504,7 +555,7 @@ declared directly  within the class or function definition:
 
 The corresponding reStructuredText documentation would be:
 
-.. code:: rst
+.. code-block:: rst
 
    .. py:class:: AnimalList[AnimalT]
 
@@ -522,7 +573,8 @@ Info field lists
 
    meta fields are added.
 
-Inside Python object description directives, reST field lists with these fields
+Inside Python object description directives,
+reStructuredText field lists with these fields
 are recognized and formatted nicely:
 
 * ``param``, ``parameter``, ``arg``, ``argument``, ``key``, ``keyword``:
@@ -604,7 +656,7 @@ word "or"::
    :vartype a_var: str or int
    :rtype: float or str
 
-.. _python-roles:
+.. _python-xref-roles:
 
 Cross-referencing Python objects
 --------------------------------
@@ -649,6 +701,10 @@ a matching identifier is found:
 
    .. note:: The role is also able to refer to property.
 
+.. rst:role:: py:type
+
+   Reference a type alias.
+
 .. rst:role:: py:exc
 
    Reference an exception.  A dotted name may be used.
diff --git a/doc/usage/domains/restructuredtext.rst b/doc/usage/domains/restructuredtext.rst
index 3a936a6..639b686 100644
--- a/doc/usage/domains/restructuredtext.rst
+++ b/doc/usage/domains/restructuredtext.rst
@@ -10,9 +10,10 @@ The reStructuredText domain (name **rst**) provides the following directives:
 
 .. rst:directive:: .. rst:directive:: name
 
-   Describes a reST directive.  The *name* can be a single directive name or
-   actual directive syntax (`..` prefix and `::` suffix) with arguments that
-   will be rendered differently.  For example::
+   Describes a reStructuredText directive.
+   The *name* can be a single directive name or actual directive syntax
+   (`..` prefix and `::` suffix) with arguments that will be rendered differently.
+   For example::
 
       .. rst:directive:: foo
 
@@ -38,7 +39,7 @@ The reStructuredText domain (name **rst**) provides the following directives:
 
 .. rst:directive:: .. rst:directive:option:: name
 
-   Describes an option for reST directive.  The *name* can be a single option
+   Describes an option for reStructuredText directive.  The *name* can be a single option
    name or option name with arguments which separated with colon (``:``).
    For example::
 
@@ -77,7 +78,7 @@ The reStructuredText domain (name **rst**) provides the following directives:
 
 .. rst:directive:: .. rst:role:: name
 
-   Describes a reST role.  For example::
+   Describes a reStructuredText role.  For example::
 
       .. rst:role:: foo
 
@@ -91,7 +92,7 @@ The reStructuredText domain (name **rst**) provides the following directives:
 
       Foo description.
 
-.. _rst-roles:
+.. _rst-xref-roles:
 
 These roles are provided to refer to the described objects:
 
diff --git a/doc/usage/domains/standard.rst b/doc/usage/domains/standard.rst
index 59b7e72..a676a2d 100644
--- a/doc/usage/domains/standard.rst
+++ b/doc/usage/domains/standard.rst
@@ -42,6 +42,44 @@ There is a set of directives allowing documenting command-line programs:
 
    ``cmdoption`` directive is a deprecated alias for the ``option`` directive.
 
+.. rst:directive:: .. confval:: name
+
+   Describes a configuration value or setting that the documented
+   code or program uses or defines.
+   Referenceable by :rst:role:`confval`.
+
+   .. rst:directive:option:: type
+      :type: text
+
+      Describes the type of the configuration value.
+      This is optional, and if specified will be interpreted as reStructuredText.
+
+   .. rst:directive:option:: default
+      :type: text
+
+      Describes the default value of the configuration value.
+      This is optional, and if specified will be interpreted as reStructuredText.
+
+   Example:
+
+   .. code-block:: rst
+
+      .. confval:: the_answer
+         :type: ``int`` (a *number*)
+         :default: **42**
+
+         This is a setting that controls the value of the answer.
+
+   will be rendered as follows:
+
+   .. confval:: the_answer
+      :no-contents-entry:
+      :no-index-entry:
+      :type: ``int`` (a *number*)
+      :default: **42**
+
+      This is a setting that controls the value of the answer.
+
 .. rst:directive:: .. envvar:: name
 
    Describes an environment variable that the documented code or program uses