sphinx-doc / sphinx-doc/sphinx

Inconsistent generation with autodata vs automodule

Open
#8,148 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

awaiting:response type:bug
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.