sphinx-doc / sphinx-doc/sphinx
Inconsistent generation with autodata vs automodule
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 am trying to independently reference a set of type definitions in a module. When I use automodule to pull them as a group, the generated docs look about as I would expect. But when I use autodata to reference one indivdually, the generated docs do not have anything other than the header.
To Reproduce
some_module.py
some_var = Union[
str,
Dict[str, List[a_typed_dict_from_elsewhere]
]
RST:
.. automodule:: some_module
:members:
:undoc-members:
:show-inheritance:
Output:
some_module.some_var # the header
alias of {the correct schema} # autodoc
^^ this is what I expect
RST:
.. autodata:: some_module.some_var
:annotation:
:noindex:
Output:
some_module.some_var # the header
^^ ie, nothing for the alias
<Paste your command-line here which cause the problem>
docs % make html
Running Sphinx v3.2.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] dev_guide/getting_started
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex py-modindexdone
writing additional pages... searchdone
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.
Expected behavior
RST:
.. autodata:: some_module.some_var
:annotation:
:noindex:
Output:
some_module.some_var # the header
alias of {the correct schema} # autodoc
Environment info
- OS: Mac 10.15.6
- Python version: 3.7.3
- Sphinx version: 3.2.1
- Sphinx extensions: [ 'sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinxcontrib.napoleon', 'sphinx_autodoc_typehints', 'sphinx_rtd_theme' ]
- Extra tools: None
Additional context
Not 100% sure I am using autodata correctly, so it could be user error.
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
Reproduce the discrepancy with the some_module.py example and the automodule and autodata RST directives, then run make html. Compare how the two directives render the some_var alias; done means autodata includes the same alias information that automodule shows.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100