sphinx-doc / sphinx-doc/sphinx
Inconsistent type references when using autodoc
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Describe the bug
I have the following python code:
"""My Implementation"""
from typing import Collection
from sphinx_autodoc.api import MyInterfaceClass
class MyClass: # pylint: disable=too-few-public-methods
"""This is my class and its doc
This is a reference to :class:`~sphinx_autodoc.api.MyInterfaceClass`
"""
delegate: MyInterfaceClass
"""Some delegate"""
external: Collection
"""Some external reference"""
def get_delegate(self) -> MyInterfaceClass:
"""Gets the delegate
Returns:
the delegate
"""
return self.delegate
def get_external(self) -> Collection:
"""Gets the delegate
Returns:
the delegate
"""
return self.external
VARIABLE: MyClass = MyClass()
"""This is my variable and its doc"""
When producing a Sphinx documentation with the following config:
extensions = [
'sphinx.ext.intersphinx',
'sphinx.ext.napoleon',
'sphinx_autodoc_typehints',
'sphinx.ext.autodoc'
]
# Some config
intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
I see the following unexpected behaviour:
- the global property
VARIABLEdoes not appear in the documentation at all - in the documentation of
MyClassI find:- the reference to
MyInterfaceClassin the docstring of the class correctly links to the documentation ofMyInterfaceClass - there is no link at all on the documentation of the type of the instance propery
delegate(https://github.com/Carsten-Leue/sphinx-autodoc/blob/master/build/docs/sphinx_autodoc.html#L189) - the styling of the the type of the instance propery
delegatevisually does not look like the styling for the same type on the return value ofget_delegate - there is no link at all on the documentation of the type of the instance propery
external(https://github.com/Carsten-Leue/sphinx-autodoc/blob/master/build/docs/sphinx_autodoc.html#L195) - the documentation of the function
get_delegate()shows the correct return type but there is no link on that type to the documentation (despite the fact that there is a link to the same class in the class level docstring) (https://github.com/Carsten-Leue/sphinx-autodoc/blob/master/build/docs/sphinx_autodoc.html#L205) - the documentation of the function
get_external()shows the correct return type and there exists a link to the documentation of the return value (but the same return value is not linked for the equivalent instance property)
- the reference to
To Reproduce
I have created a small test repo to illustrate and reproduce the issue:
- clone
https://github.com/Carsten-Leue/sphinx-autodoc - install
tox - run
tox -e doc
The result of this step is also checked in at https://github.com/Carsten-Leue/sphinx-autodoc/tree/master/build/docs
Expected behavior
- Linking to types in my own project (across submodules) works consistently, everywhere where a type gets referenced, i.e. in types for arguments, return values, variables and refences in doc strings
Your project
https://github.com/Carsten-Leue/sphinx-autodoc
Environment info
- OS: Windoes 10
- Python version: Python 3.8.4 (tags/v3.8.4:dfa645a, Jul 13 2020, 16:46:45) [MSC v.1924 64 bit (AMD64)] on win32
- Sphinx version: 3.1.2
- Sphinx extensions: ['sphinx.ext.intersphinx',
'sphinx.ext.napoleon',
'sphinx_autodoc_typehints',
'sphinx.ext.autodoc']
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Clone the linked reproduction repository and run tox -e doc; inspect the generated pages under build/docs and compare links for class docstrings, properties, return values, and the global variable. Trace the autodoc and sphinx_autodoc_typehints handling for these references, then verify that equivalent project and external type references render consistently.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100