fixup! Add py:type directive and role

Author: AWhetter

doc/usage/domains/python.rst

@@ -124,9 +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 documented
-   with :rst:dir:`py:attribute`.  Type aliases are documented with
-   :rst:dir:`py:type`.
+   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,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.  Type aliases are documented with :rst:dir:`py:type`.
+   changed directly.  Type aliases should be documented with :rst:dir:`py:type`.
 
    .. rubric:: options
 
@@ -318,17 +318,33 @@ The following directives are provided for module and class contents:
 
 .. 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.
+   Describe a :ref:`type alias <python:type-aliases>`.
 
-   .. versionadded:: 7.3
+   This directive supports an optional description body, e.g.::
+
+   .. code-block:: rst
+
+      .. py:type:: UInt64
+
+         Represent a 64-bit positive integer.
 
    .. rubric:: options
 
-   .. rst:directive:option:: type: the type that the alias represents
+   .. rst:directive:option:: canonical
       :type: text
 
+      The canonical type represented by this alias, e.g.::
+
+      .. code-block:: rst
+
+         .. py:type:: StrPattern
+
+            :canonical: str | re.Pattern[str]
+
+            Represent a regular expression or a compiled pattern.
+
+   .. versionadded:: 7.3
+
 .. rst:directive:: .. py:method:: name(parameters)
                    .. py:method:: name[type parameters](parameters)
 

sphinx/domains/python/__init__.py

@@ -393,9 +393,9 @@ def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
 class PyTypeAlias(PyObject):
     """Description of a type alias."""
 
-    option_spec: OptionSpec = PyObject.option_spec.copy()
+    option_spec: ClassVar[OptionSpec] = PyObject.option_spec.copy()
     option_spec.update({
-        'value': directives.unchanged,
+        'canonical': directives.unchanged,
     })
 
     def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
@@ -404,10 +404,10 @@ def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
     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, '',
+        canonical = self.options.get('canonical')
+        if canonical:
+            annotations = _parse_annotation(canonical, self.env)
+            signode += addnodes.desc_annotation(canonical, '',
                                                 addnodes.desc_sig_space(),
                                                 addnodes.desc_sig_punctuation('', '='),
                                                 addnodes.desc_sig_space(),

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

@@ -8,3 +8,4 @@ test-domain-py
     module_option
     abbr
     canonical
+    type_alias

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

@@ -66,4 +66,4 @@ module
     :type: typing.Literal[-2]
 
 .. py:type:: MyType1
-    :value: list[int | str]
+    :canonical: list[int | str]

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

@@ -0,0 +1,15 @@
+Type Alias
+==========
+
+.. py:module:: module_two
+
+   .. py:class:: SomeClass
+
+:py:type:`.MyAlias`
+:any:`MyAlias`
+:any:`module_one.MyAlias`
+
+.. py:module:: module_one
+
+   .. py:type:: MyAlias
+      :canonical: list[int | module_two.SomeClass]

tests/test_domains/test_domain_py_pyobject.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import pytest
 from docutils import nodes
 
 from sphinx import addnodes
@@ -365,12 +366,12 @@ def test_pyproperty(app):
 def test_pytypealias(app):
     text = (".. py:module:: example\n"
             ".. py:type:: Alias1\n"
-            "   :value: list[str | int]\n"
+            "   :canonical: list[str | int]\n"
             "\n"
             ".. py:class:: Class\n"
             "\n"
             "   .. py:type:: Alias2\n"
-            "      :value: int\n")
+            "      :canonical: int\n")
     domain = app.env.get_domain('py')
     doctree = restructuredtext.parse(app, text)
     assert_node(doctree, (addnodes.index,
@@ -413,6 +414,25 @@ def test_pytypealias(app):
     assert domain.objects['example.Class.Alias2'] == ('index', 'example.Class.Alias2', 'type', False)
 
 
+@pytest.mark.sphinx('html', testroot='domain-py', freshenv=True)
+def test_domain_py_type_alias(app, status, warning):
+    app.build(force_all=True)
+
+    content = (app.outdir / 'type_alias.html').read_text(encoding='utf8')
+    assert ('<em class="property"><span class="pre">type</span><span class="w"> </span></em>'
+            '<span class="sig-prename descclassname"><span class="pre">module_one.</span></span>'
+            '<span class="sig-name descname"><span class="pre">MyAlias</span></span>'
+            '<em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span>'
+            '<span class="w"> </span><span class="pre">list</span>'
+            '<span class="p"><span class="pre">[</span></span>'
+            '<span class="pre">int</span><span class="w"> </span>'
+            '<span class="p"><span class="pre">|</span></span><span class="w"> </span>'
+            '<a class="reference internal" href="#module_two.SomeClass" title="module_two.SomeClass">'
+            '<span class="pre">module_two.SomeClass</span></a>'
+            '<span class="p"><span class="pre">]</span></span></em>' in content)
+    assert warning.getvalue() == ''
+
+
 def test_pydecorator_signature(app):
     text = ".. py:decorator:: deco"
     domain = app.env.get_domain('py')