Open
5 of 40 issues completedDescription
This issue serves as a tracker for issues related to autodoc and its inhability to render types. Feel free to dump the issues you find relevant and I'll add them to this tracker. That way, people can easily find them and we can also find what is missing or not.
TYPE_CHECKING
guarded imports
- Type hints are irregularly documented (+link generation broken) #9813
- Autodoc does not support
if TYPE_CHECKING
imports #11225 - More than one target found for cross-reference with quotes around type annotation #10400
automodule
does not work withTYPE_CHECKING
guarded code #13137
Forward References and from __future__ import annotations
- Type hints are irregularly documented (+link generation broken) #9813
- Autodoc has trouble with type hinting generics and class name forward references #11327
Type variables and new types treated as data
instead of class
- Autodoc parameter types in parameter list not resolving for TypeVar or aliases #9705
- References to TypeVars are not resolved when using autodoc_typehints = "description" #9172
- Autodoc parameter types in parameter list not resolving for TypeVar or aliases #9705
- TypeVar objects not documenting as expected #9980
- autosummary generation considers
NewType
instances to be data, but autodoc considers them a class #11552
Undefined references to pathlib.Path
and co.
None
and Optional
not linking correctly:
- Use aliases in parameter type annotations where they are available #9740
- Option for display mode of Optional[Union]. #10773
- Intersphinx: Create link for Optional in description even if it is an inherited docstring #10793
- py domain:
None
is no longer hyperlinked after 4.4.0 #10899 - PEP 604 Syntax Fails on Imported Types with Automock Imports #11211
- Inconsistent output for optional parameters/attributes #11522
Using optional as keyword misidentified as type:
Literal
types not linking correctly:
- autodoc does not generate correct reStructuredText when type hints contain special characters #9266
autodoc_type_aliases
not working withtyping.Literal
type aliases... #10525- sphinx.ext.autodoc: Typehints, aliases, and (internal/external) cross-references #10794
- py domain markup w/ typing annotations with Literal[] and non \w characters doesn't render #11156
Returns
section types not linking:
Yield
section types not linking correctly:
Generic types not linking:
- tuple with generic parameter not correctly documented with autodoc_typehints = 'description' (result of signature is ok) #10873
- autoclass does not work for concrete aliases of a generic type #7450
@dataclass
specific linking bugs:
- Dataclass field types are not rendered when factories are used #10893
- Docs from dataclass descriptor fields #11672
@property
return type:
- Issue documenting decorators that return classes. #10221
autodoc-process-signature
does not populate return signature for properties #10396- Return type for Yield attribute not properly hyperlinked in apidocs #8004
General alias linking problems:
- Make
default_role
aware of aliases. #9453 - [autodoc] undefined reference for aliased type annotation in the class constructor #12286
Napoleon specific:
Docstring extraction
Miscellaneous
- Inconsistent type references when using autodoc #7972
- [BUG] singledispatch classmethods are not detected by MethodDocumenter #11278
- autodoc_typehints cause bogus
Return type
sections to be generated in autoclass #12472
Under consideration (Python 3.9 failure only)
Tasks issues
Possible solutions
For people that want some solutions:
- Consider using
autodoc_type_aliases
(the support is limited and does not work for missing references in class signatures for instance). - Ignore the warnings by specifying entries in
nitpick_ignore
(it does not solve everything but at least you know what is wrong). Be careful though since sometimes names are incorrectly resolved because they are thought to be the same... (e.g., importingdocutils.nodes.Node
and_pytest.nodes.Node
asNode
and usingNode
in an annotation uses the first reference it finds ifNode
is not available at runtime, e.g., guarded in a TYPE_CHECKING block). - Maybe try sphinx-autodoc2 or sphinx-autodoc-typehints.