Allow unqualified type hint names in generated docs #7119
Description
It would be great if the current type hinting work would support removing qualification from type names. For some modules, the types may be deeply nested which will more easily break the page layout.
Definitions (by example)
- Qualified name:
pkg.module.ClassName - Unqualified name:
ClassName
Example
from typing import Tuple
from numpy.polynomial import polynomial
def multiply_polynomial(
p: polynomial.Polynomial, value: int
) -> Tuple[polynomial.Polynomial, polynomial.Polynomial]:
return p, polynomial.Polynomial(*(value * p.coef))In this code, the type is polynomial.Polynomial but the fully qualified name is numpy.polynomial.polynomial.Polynomial which is what will show up in the docs.
With the following in conf.py
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.autodoc.typehints",
]
autodoc_typehints = "description"We'd see some generated docs similar to
mypkg.mymodule.multiply_polynomial(p, value)
Parameters: * p (numpy.polynomial.polynomial.Polynomial) –
* value (int) –
Return type: Tuple[numpy.polynomial.polynomial.Polynomial, numpy.polynomial.polynomial.Polynomial]
Instead, with unqualified names, we'd have a much simpler
mypkg.mymodule.multiply_polynomial(p, value)
Parameters: * p (Polynomial) –
* value (int) –
Return type: Tuple[Polynomial, Polynomial]
Rationale
Full qualification inherently gives more context, so it is a sane default. However, intersphinx linkage to the correct types gives even better context, since you can just follow directly to the actual type definition. With both intersphinx linkage and unqualified type names, you can have the best of both worlds: readability and quick disambiguation.
Similar prior work
The external extension https://github.com/agronholm/sphinx-autodoc-typehints collapses the name to the unqualified name by default, unless otherwise opted for, for an example of how this might work.
Variant
One possible issue with the above is that there's still no direct control of the type name---either you get the ClassName, or you get the fully.qualified.ClassName. An alternative may be to use whatever is used in the source code. E.g., if the code has import fully.qualified as qual and uses qual.ClassName in the signature, then Sphinx can respect that. +1 because the docs follow the code, but -1 because no consistency is guaranteed. All three versions could possibly be supported, though, and left up to the maintainer which style they go with.
With the above code example, this variant would turn the generated docs into:
mypkg.mymodule.multiply_polynomial(p, value)
Parameters: * p (polynomial.Polynomial) –
* value (int) –
Return type: Tuple[polynomial.Polynomial, polynomial.Polynomial]