1 files changed, 62 insertions, 6 deletions
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.