Add py:type directive and role

Closes #7896

Author: AWhetter

CHANGES.rst

@@ -166,6 +166,9 @@ Features added
   to annotate the return type of their ``setup`` function.
   Patch by Chris Sewell.
 
+* #7896: Python Domain: Add a :rst:dir:`py:type` directive for documenting
+  type aliases, and a :rst:role:`py:type` role for linking to them.
+
 Bugs fixed
 ----------
 

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."  Class and object attributes are documented
+   with :rst:dir:`py:attribute`.  Type aliases are documented with
+   :rst:dir:`py:type`.
 
    .. rubric:: options
 
@@ -258,7 +259,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.
+   changed directly.  Type aliases are documented with :rst:dir:`py:type`.
 
    .. rubric:: options
 
@@ -315,6 +316,19 @@ 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
+
+   Describes a :ref:`type alias <python:type-aliases>`.  A description of
+   the type alias, such as the docstring can be, placed in the body of
+   the directive.
+
+   .. versionadded:: 7.3
+
+   .. rubric:: options
+
+   .. rst:directive:option:: type: the type that the alias represents
+      :type: text
+
 .. rst:directive:: .. py:method:: name(parameters)
                    .. py:method:: name[type parameters](parameters)
 
@@ -649,6 +663,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.

sphinx/domains/python/__init__.py

@@ -390,6 +390,46 @@ def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
         return _('%s (%s property)') % (attrname, clsname)
 
 
+class PyTypeAlias(PyObject):
+    """Description of a type alias."""
+
+    option_spec: OptionSpec = PyObject.option_spec.copy()
+    option_spec.update({
+        'value': directives.unchanged,
+    })
+
+    def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
+        return [nodes.Text('type'), addnodes.desc_sig_space()]
+
+    def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
+        fullname, prefix = super().handle_signature(sig, signode)
+
+        value = self.options.get('value')
+        if value:
+            annotations = _parse_annotation(value, self.env)
+            signode += addnodes.desc_annotation(value, '',
+                                                addnodes.desc_sig_space(),
+                                                addnodes.desc_sig_punctuation('', '='),
+                                                addnodes.desc_sig_space(),
+                                                *annotations)
+
+        return fullname, prefix
+
+    def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
+        name, cls = name_cls
+        try:
+            clsname, attrname = name.rsplit('.', 1)
+            if modname and self.env.config.add_module_names:
+                clsname = f'{modname}.{clsname}'
+        except ValueError:
+            if modname:
+                return _('%s (in module %s)') % (name, modname)
+            else:
+                return name
+
+        return _('%s (type alias in %s)') % (attrname, clsname)
+
+
 class PyModule(SphinxDirective):
     """
     Directive to mark description of a new module.
@@ -594,6 +634,7 @@ class PythonDomain(Domain):
         'staticmethod': ObjType(_('static method'), 'meth', 'obj'),
         'attribute':    ObjType(_('attribute'),     'attr', 'obj'),
         'property':     ObjType(_('property'),      'attr', '_prop', 'obj'),
+        'type':         ObjType(_('type alias'),    'type', 'obj'),
         'module':       ObjType(_('module'),        'mod', 'obj'),
     }
 
@@ -607,6 +648,7 @@ class PythonDomain(Domain):
         'staticmethod':    PyStaticMethod,
         'attribute':       PyAttribute,
         'property':        PyProperty,
+        'type':            PyTypeAlias,
         'module':          PyModule,
         'currentmodule':   PyCurrentModule,
         'decorator':       PyDecoratorFunction,
@@ -619,6 +661,7 @@ class PythonDomain(Domain):
         'class': PyXRefRole(),
         'const': PyXRefRole(),
         'attr':  PyXRefRole(),
+        'type':  PyXRefRole(),
         'meth':  PyXRefRole(fix_parens=True),
         'mod':   PyXRefRole(),
         'obj':   PyXRefRole(),

tests/roots/test-domain-py/module.rst

@@ -64,3 +64,6 @@ module
 
 .. py:data:: test2
     :type: typing.Literal[-2]
+
+.. py:type:: MyType1
+    :value: list[int | str]

tests/roots/test-domain-py/roles.rst

@@ -5,14 +5,19 @@ roles
 
 .. py:method:: top_level
 
+.. py:type:: TopLevelType
+
 * :py:class:`TopLevel`
 * :py:meth:`top_level`
+* :py:type:`TopLevelType`
 
 
 .. py:class:: NestedParentA
 
     * Link to :py:meth:`child_1`
 
+    .. py:type:: NestedTypeA
+
     .. py:method:: child_1()
 
         * Link to :py:meth:`NestedChildA.subchild_2`
@@ -46,3 +51,4 @@ roles
         * Link to :py:class:`NestedParentB`
 
 * :py:class:`NestedParentA.NestedChildA`
+* :py:type:`NestedParentA.NestedTypeA`

tests/test_domains/test_domain_py.py

@@ -92,19 +92,21 @@ def assert_refnode(node, module_name, class_name, target, reftype=None,
     refnodes = list(doctree.findall(pending_xref))
     assert_refnode(refnodes[0], None, None, 'TopLevel', 'class')
     assert_refnode(refnodes[1], None, None, 'top_level', 'meth')
-    assert_refnode(refnodes[2], None, 'NestedParentA', 'child_1', 'meth')
-    assert_refnode(refnodes[3], None, 'NestedParentA', 'NestedChildA.subchild_2', 'meth')
-    assert_refnode(refnodes[4], None, 'NestedParentA', 'child_2', 'meth')
-    assert_refnode(refnodes[5], False, 'NestedParentA', 'any_child', domain='')
-    assert_refnode(refnodes[6], None, 'NestedParentA', 'NestedChildA', 'class')
-    assert_refnode(refnodes[7], None, 'NestedParentA.NestedChildA', 'subchild_2', 'meth')
-    assert_refnode(refnodes[8], None, 'NestedParentA.NestedChildA',
+    assert_refnode(refnodes[2], None, None, 'TopLevelType', 'type')
+    assert_refnode(refnodes[3], None, 'NestedParentA', 'child_1', 'meth')
+    assert_refnode(refnodes[4], None, 'NestedParentA', 'NestedChildA.subchild_2', 'meth')
+    assert_refnode(refnodes[5], None, 'NestedParentA', 'child_2', 'meth')
+    assert_refnode(refnodes[6], False, 'NestedParentA', 'any_child', domain='')
+    assert_refnode(refnodes[7], None, 'NestedParentA', 'NestedChildA', 'class')
+    assert_refnode(refnodes[8], None, 'NestedParentA.NestedChildA', 'subchild_2', 'meth')
+    assert_refnode(refnodes[9], None, 'NestedParentA.NestedChildA',
                    'NestedParentA.child_1', 'meth')
-    assert_refnode(refnodes[9], None, 'NestedParentA', 'NestedChildA.subchild_1', 'meth')
-    assert_refnode(refnodes[10], None, 'NestedParentB', 'child_1', 'meth')
-    assert_refnode(refnodes[11], None, 'NestedParentB', 'NestedParentB', 'class')
-    assert_refnode(refnodes[12], None, None, 'NestedParentA.NestedChildA', 'class')
-    assert len(refnodes) == 13
+    assert_refnode(refnodes[10], None, 'NestedParentA', 'NestedChildA.subchild_1', 'meth')
+    assert_refnode(refnodes[11], None, 'NestedParentB', 'child_1', 'meth')
+    assert_refnode(refnodes[12], None, 'NestedParentB', 'NestedParentB', 'class')
+    assert_refnode(refnodes[13], None, None, 'NestedParentA.NestedChildA', 'class')
+    assert_refnode(refnodes[14], None, None, 'NestedParentA.NestedTypeA', 'type')
+    assert len(refnodes) == 15
 
     doctree = app.env.get_doctree('module')
     refnodes = list(doctree.findall(pending_xref))
@@ -135,7 +137,10 @@ def assert_refnode(node, module_name, class_name, target, reftype=None,
     assert_refnode(refnodes[15], False, False, 'index', 'doc', domain='std')
     assert_refnode(refnodes[16], False, False, 'typing.Literal', 'obj', domain='py')
     assert_refnode(refnodes[17], False, False, 'typing.Literal', 'obj', domain='py')
-    assert len(refnodes) == 18
+    assert_refnode(refnodes[18], False, False, 'list', 'class', domain='py')
+    assert_refnode(refnodes[19], False, False, 'int', 'class', domain='py')
+    assert_refnode(refnodes[20], False, False, 'str', 'class', domain='py')
+    assert len(refnodes) == 21
 
     doctree = app.env.get_doctree('module_option')
     refnodes = list(doctree.findall(pending_xref))
@@ -191,7 +196,9 @@ def test_domain_py_objects(app, status, warning):
 
     assert objects['TopLevel'][2] == 'class'
     assert objects['top_level'][2] == 'method'
+    assert objects['TopLevelType'][2] == 'type'
     assert objects['NestedParentA'][2] == 'class'
+    assert objects['NestedParentA.NestedTypeA'][2] == 'type'
     assert objects['NestedParentA.child_1'][2] == 'method'
     assert objects['NestedParentA.any_child'][2] == 'method'
     assert objects['NestedParentA.NestedChildA'][2] == 'class'
@@ -233,6 +240,9 @@ def find_obj(modname, prefix, obj_name, obj_type, searchmode=0):
     assert (find_obj(None, None, 'NONEXISTANT', 'class') == [])
     assert (find_obj(None, None, 'NestedParentA', 'class') ==
             [('NestedParentA', ('roles', 'NestedParentA', 'class', False))])
+    assert (find_obj(None, None, 'NestedParentA.NestedTypeA', 'type') ==
+            [('NestedParentA.NestedTypeA',
+              ('roles', 'NestedParentA.NestedTypeA', 'type', False))])
     assert (find_obj(None, None, 'NestedParentA.NestedChildA', 'class') ==
             [('NestedParentA.NestedChildA',
               ('roles', 'NestedParentA.NestedChildA', 'class', False))])

tests/test_domains/test_domain_py_pyobject.py

@@ -362,6 +362,57 @@ def test_pyproperty(app):
     assert domain.objects['Class.prop2'] == ('index', 'Class.prop2', 'property', False)
 
 
+def test_pytypealias(app):
+    text = (".. py:module:: example\n"
+            ".. py:type:: Alias1\n"
+            "   :value: list[str | int]\n"
+            "\n"
+            ".. py:class:: Class\n"
+            "\n"
+            "   .. py:type:: Alias2\n"
+            "      :value: int\n")
+    domain = app.env.get_domain('py')
+    doctree = restructuredtext.parse(app, text)
+    assert_node(doctree, (addnodes.index,
+                          addnodes.index,
+                          nodes.target,
+                          [desc, ([desc_signature, ([desc_annotation, ('type', desc_sig_space)],
+                                                    [desc_addname, 'example.'],
+                                                    [desc_name, 'Alias1'],
+                                                    [desc_annotation, (desc_sig_space,
+                                                                       [desc_sig_punctuation, '='],
+                                                                       desc_sig_space,
+                                                                       [pending_xref, 'list'],
+                                                                       [desc_sig_punctuation, '['],
+                                                                       [pending_xref, 'str'],
+                                                                       desc_sig_space,
+                                                                       [desc_sig_punctuation, '|'],
+                                                                       desc_sig_space,
+                                                                       [pending_xref, 'int'],
+                                                                       [desc_sig_punctuation, ']'],
+                                                                       )])],
+                                  [desc_content, ()])],
+                          addnodes.index,
+                          [desc, ([desc_signature, ([desc_annotation, ('class', desc_sig_space)],
+                                                    [desc_addname, 'example.'],
+                                                    [desc_name, 'Class'])],
+                                  [desc_content, (addnodes.index,
+                                                  desc)])]))
+    assert_node(doctree[5][1][0], addnodes.index,
+                entries=[('single', 'Alias2 (type alias in example.Class)', 'example.Class.Alias2', '', None)])
+    assert_node(doctree[5][1][1], ([desc_signature, ([desc_annotation, ('type', desc_sig_space)],
+                                                     [desc_name, 'Alias2'],
+                                                     [desc_annotation, (desc_sig_space,
+                                                                        [desc_sig_punctuation, '='],
+                                                                        desc_sig_space,
+                                                                        [pending_xref, 'int'])])],
+                                   [desc_content, ()]))
+    assert 'example.Alias1' in domain.objects
+    assert domain.objects['example.Alias1'] == ('index', 'example.Alias1', 'type', False)
+    assert 'example.Class.Alias2' in domain.objects
+    assert domain.objects['example.Class.Alias2'] == ('index', 'example.Class.Alias2', 'type', False)
+
+
 def test_pydecorator_signature(app):
     text = ".. py:decorator:: deco"
     domain = app.env.get_domain('py')