sphinx-doc / sphinx-doc/sphinx
Autosummary 'attributes' template variable excludes some module attributes
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
Commit 784d4cb36a2aca4bcb2c773db2506cc609a2a18a broke autosummary's computation of module attributes (added in #7469). Specifically, the attributes template variable now wrongly excludes any module attribute whose value is an object created in another module.
To Reproduce
Apply autosummary to a module with a documented attribute whose value is an instance of a class defined in another module. The attribute will not be listed in the generated documentation (see example project below).
Expected behavior
The attributes template variable should include all documented attributes defined in the module (there is no question of trying to hide "imported members" here, since if you import a name at module-level then it will not have a docstring or doc-comment).
Your project
Here is a tiny project triggering the bug (testA.thing1 is properly documented, but the entry for testA.thing2 is missing): example2.zip
Environment info
- OS: macOS 10.14.6
- Python version: 3.8.0
- Sphinx version: 3.3.0 (I tested against the 3.x branch)
- Sphinx extensions:
sphinx.ext.autodoc,sphinx.ext.autosummary
Additional context
The error was introduced by commit 784d4cb36a2aca4bcb2c773db2506cc609a2a18a: when autosummary.generate.generate_autosummary_content calls get_module_attrs, it passes in the list of members ns['members']. This used to be the same as dir(obj), but now uses ModuleScanner to exclude imported members. ModuleScanner introspects the value of the member to check whether it was defined elsewhere, which doesn't make sense for module-level attributes. You can fix the bug by simply calling get_module_attrs with dir(obj).
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
Start in autosummary.generate.generate_autosummary_content and trace its call to get_module_attrs, comparing the members list with dir(obj) and how ModuleScanner handles module-level values. Reproduce the issue with the linked example project, then verify that the generated documentation includes documented attributes whose values are objects from another module.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 55/100