Autodoc: add :canonical: for all object types

sphinx/ext/autodoc/__init__.py

@@ -1260,7 +1260,43 @@ def keyfunc(entry: tuple[Documenter, bool]) -> int:
             return super().sort_members(documenters, order)
 
 
-class ModuleLevelDocumenter(Documenter):
+class PyObjectDocumenter(Documenter):
+    """Documenter for everything except modules"""
+
+    def add_directive_header(self, sig: str) -> None:
+        super().add_directive_header(sig)
+        self.add_canonical_option()
+
+    def add_canonical_option(self) -> None:
+        canonical_fullname = self.get_canonical_fullname()
+        if (
+            not isinstance(self.object, NewType)
+            and canonical_fullname
+            and self.fullname != canonical_fullname
+        ):
+            source_name = self.get_sourcename()
+            self.add_line(f'   :canonical: {canonical_fullname}', source_name)
+
+    def get_canonical_fullname(self) -> str | None:
+        modname = safe_getattr(self.object, '__module__', self.modname)
+        if not modname:
+            return None
+
+        name = safe_getattr(self.object, '__qualname__', None)
+        if name is None:
+            name = safe_getattr(self.object, '__name__', None)
+            if name is None:
+                return None
+
+        if all(map(str.isidentifier, name.split('.'))):
+            return f'{modname}.{name}'
+
+        # qualname doesn't exist or is not valid
+        # (e.g. object is defined as <locals>)
+        return None
+
+
+class ModuleLevelDocumenter(PyObjectDocumenter):
     """Specialized Documenter subclass for objects on module level (functions,
     classes, data/constants).
     """
@@ -1272,6 +1308,9 @@ def resolve_name(
             return modname, [*parents, base]
         if path:
             modname = path.rstrip('.')
+            if modname.startswith('builtins.'):
+                modname, name = modname.split('.', 1)
+                parents = [*parents, name]
             return modname, [*parents, base]
 
         # if documenting a toplevel object without explicit module,
@@ -1284,7 +1323,7 @@ def resolve_name(
         return modname, [*parents, base]
 
 
-class ClassLevelDocumenter(Documenter):
+class ClassLevelDocumenter(PyObjectDocumenter):
     """Specialized Documenter subclass for objects on class level (methods,
     attributes).
     """
@@ -1844,19 +1883,9 @@ def get_overloaded_signatures(self) -> list[Signature]:
 
         return []
 
-    def get_canonical_fullname(self) -> str | None:
-        __modname__ = safe_getattr(self.object, '__module__', self.modname)
-        __qualname__ = safe_getattr(self.object, '__qualname__', None)
-        if __qualname__ is None:
-            __qualname__ = safe_getattr(self.object, '__name__', None)
-        if __qualname__ and '<locals>' in __qualname__:
-            # No valid qualname found if the object is defined as locals
-            __qualname__ = None
-
-        if __modname__ and __qualname__:
-            return f'{__modname__}.{__qualname__}'
-        else:
-            return None
+    def add_canonical_option(self) -> None:
+        if not self.doc_as_attr:
+            super().add_canonical_option()
 
     def add_directive_header(self, sig: str) -> None:
         sourcename = self.get_sourcename()

tests/roots/test-ext-autodoc/target/canonical/__init__.py

@@ -1 +1 @@
-from target.canonical.original import Bar, Foo
+from target.canonical.original import Bar, Foo, bar

tests/roots/test-ext-autodoc/target/canonical/original.py

@@ -6,6 +6,8 @@ def meth(self):
 
 
 def bar():
+    """docstring"""
+
     class Bar:
         """docstring"""
 

tests/test_extensions/test_ext_autodoc.py

@@ -1522,6 +1522,7 @@ def _node(
         *,
         args: str,
         indent: int,
+        canonical: bool = False,
         **options: Any,
     ) -> list[str]:
         prefix = indent * ' '
@@ -1535,8 +1536,10 @@ def rst_option(name: str, value: Any) -> str:
             '',
             f'{prefix}.. py:{role}:: {name}{args}',
             f'{prefix}{tab}:module: {self.module}',
-            *itertools.starmap(rst_option, options.items()),
         ]
+        if canonical:
+            lines.append(f'{prefix}{tab}:canonical: {self.module}.{name}')
+        lines += itertools.starmap(rst_option, options.items())
         if doc:
             lines.extend(['', f'{prefix}{tab}{doc}'])
         lines.append('')
@@ -1550,11 +1553,20 @@ def entry(
         role: str,
         args: str = '',
         indent: int = 3,
+        canonical: bool = False,
         **rst_options: Any,
     ) -> list[str]:
         """Get the RST lines for a named attribute, method, etc."""
         qualname = f'{self.name}.{entry_name}'
-        return self._node(role, qualname, doc, args=args, indent=indent, **rst_options)
+        return self._node(
+            role,
+            qualname,
+            doc,
+            args=args,
+            indent=indent,
+            canonical=canonical,
+            **rst_options,
+        )
 
     def preamble_lookup(
         self, doc: str, *, indent: int = 0, **options: Any
@@ -1619,15 +1631,37 @@ def method(
         *flags: str,
         args: str = '()',
         indent: int = 3,
+        canonical: bool = False,
     ) -> list[str]:
         rst_options = dict.fromkeys(flags, '')
         return self.entry(
-            name, doc, role='method', args=args, indent=indent, **rst_options
+            name,
+            doc,
+            role='method',
+            args=args,
+            indent=indent,
+            canonical=canonical,
+            **rst_options,
         )
 
-    def member(self, name: str, value: Any, doc: str, *, indent: int = 3) -> list[str]:
+    def member(
+        self,
+        name: str,
+        value: Any,
+        doc: str,
+        *,
+        indent: int = 3,
+        canonical: bool = False,
+    ) -> list[str]:
         rst_options = {'value': repr(value)}
-        return self.entry(name, doc, role='attribute', indent=indent, **rst_options)
+        return self.entry(
+            name,
+            doc,
+            role='attribute',
+            indent=indent,
+            canonical=canonical,
+            **rst_options,
+        )
 
 
 @pytest.fixture
@@ -1691,8 +1725,8 @@ def test_enum_class_with_data_type(app, autodoc_enum_options):
     actual = do_autodoc(app, 'class', fmt.target, options)
     assert list(actual) == [
         *fmt.preamble_lookup('this is enum class'),
-        *fmt.entry('dtype', 'docstring', role='property'),
-        *fmt.method('isupper', 'inherited'),
+        *fmt.entry('dtype', 'docstring', role='property', canonical=True),
+        *fmt.method('isupper', 'inherited', canonical=True),
         *fmt.method('say_goodbye', 'docstring', 'classmethod'),
         *fmt.method('say_hello', 'docstring'),
         *fmt.member('x', 'x', ''),
@@ -2129,12 +2163,74 @@ def test_bound_method(app):
         '',
         '.. py:function:: bound_method()',
         '   :module: target.bound_method',
+        '   :canonical: target.bound_method.Cls.method',
         '',
         '   Method docstring',
         '',
     ]
 
 
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_coroutine(app):
+    actual = do_autodoc(app, 'function', 'target.functions.coroutinefunc')
+    assert list(actual) == [
+        '',
+        '.. py:function:: coroutinefunc()',
+        '   :module: target.functions',
+        '   :async:',
+        '',
+    ]
+
+    options = {'members': None}
+    actual = do_autodoc(app, 'class', 'target.coroutine.AsyncClass', options)
+    assert list(actual) == [
+        '',
+        '.. py:class:: AsyncClass()',
+        '   :module: target.coroutine',
+        '',
+        '',
+        '   .. py:method:: AsyncClass.do_asyncgen()',
+        '      :module: target.coroutine',
+        '      :async:',
+        '',
+        '      A documented async generator',
+        '',
+        '',
+        '   .. py:method:: AsyncClass.do_coroutine()',
+        '      :module: target.coroutine',
+        '      :async:',
+        '',
+        '      A documented coroutine function',
+        '',
+        '',
+        '   .. py:method:: AsyncClass.do_coroutine2()',
+        '      :module: target.coroutine',
+        '      :async:',
+        '      :classmethod:',
+        '',
+        '      A documented coroutine classmethod',
+        '',
+        '',
+        '   .. py:method:: AsyncClass.do_coroutine3()',
+        '      :module: target.coroutine',
+        '      :async:',
+        '      :staticmethod:',
+        '',
+        '      A documented coroutine staticmethod',
+        '',
+    ]
+
+    # force-synchronized wrapper
+    actual = do_autodoc(app, 'function', 'target.coroutine.sync_func')
+    assert list(actual) == [
+        '',
+        '.. py:function:: sync_func()',
+        '   :module: target.coroutine',
+        '   :canonical: target.coroutine._other_coro_func',
+        '',
+    ]
+
+
 @pytest.mark.sphinx('html', testroot='ext-autodoc')
 def test_partialmethod(app):
     expected = [
@@ -3098,9 +3194,17 @@ def test_canonical(app):
         '',
         '   .. py:method:: Foo.meth()',
         '      :module: target.canonical',
+        '      :canonical: target.canonical.original.Foo.meth',
         '',
         '      docstring',
         '',
+        '',
+        '.. py:function:: bar()',
+        '   :module: target.canonical',
+        '   :canonical: target.canonical.original.bar',
+        '',
+        '   docstring',
+        '',
     ]
 
 

tests/test_extensions/test_ext_autodoc_autoattribute.py

@@ -145,6 +145,7 @@ def test_autoattribute_GenericAlias(app):
         '',
         '.. py:attribute:: Class.T',
         '   :module: target.genericalias',
+        '   :canonical: typing.List',
         '',
         '   A list of int',
         '',
@@ -153,6 +154,21 @@ def test_autoattribute_GenericAlias(app):
     ]
 
 
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_autoattribute_TypeVar(app):
+    actual = do_autodoc(app, 'attribute', 'target.typevar.Class.T1')
+    assert list(actual) == [
+        '',
+        '.. py:attribute:: Class.T1',
+        '   :module: target.typevar',
+        '   :canonical: target.typevar.T1',
+        '   :value: ~T1',
+        '',
+        '   T1',
+        '',
+    ]
+
+
 @pytest.mark.sphinx('html', testroot='ext-autodoc')
 def test_autoattribute_hide_value(app):
     actual = do_autodoc(app, 'attribute', 'target.hide_value.Foo.SENTINEL1')

tests/test_extensions/test_ext_autodoc_autoclass.py

@@ -526,6 +526,7 @@ def test_autoattribute_TypeVar_module_level(app):
         '',
         '.. py:class:: Class.T1',
         '   :module: target.typevar',
+        '   :canonical: target.typevar.T1',
         '',
         '   T1',
         '',

tests/test_extensions/test_ext_autodoc_autodata.py

@@ -75,6 +75,7 @@ def test_autodata_GenericAlias(app):
         '',
         '.. py:data:: T',
         '   :module: target.genericalias',
+        '   :canonical: typing.List',
         '',
         '   A list of int',
         '',

tests/test_extensions/test_ext_autodoc_autofunction.py

@@ -71,6 +71,7 @@ def test_method(app):
         '',
         '.. py:function:: method(arg1, arg2)',
         '   :module: target.callable',
+        '   :canonical: target.callable.Callable.method',
         '',
         '   docstring of Callable.method().',
         '',
@@ -79,11 +80,14 @@ def test_method(app):
 
 @pytest.mark.sphinx('html', testroot='ext-autodoc')
 def test_builtin_function(app):
+    import os
+
     actual = do_autodoc(app, 'function', 'os.umask')
     assert list(actual) == [
         '',
         '.. py:function:: umask(mask, /)',
         '   :module: os',
+        f'   :canonical: {os.name}.umask',
         '',
         '   Set the current numeric umask and return the previous umask.',
         '',
@@ -95,8 +99,8 @@ def test_methoddescriptor(app):
     actual = do_autodoc(app, 'function', 'builtins.int.__add__')
     assert list(actual) == [
         '',
-        '.. py:function:: __add__(self, value, /)',
-        '   :module: builtins.int',
+        '.. py:function:: int.__add__(self, value, /)',
+        '   :module: builtins',
         '',
         '   Return self+value.',
         '',
@@ -192,6 +196,7 @@ def test_synchronized_coroutine(app):
         '',
         '.. py:function:: sync_func()',
         '   :module: target.coroutine',
+        '   :canonical: target.coroutine._other_coro_func',
         '',
     ]