sphinx-doc / sphinx-doc/sphinx

Autosummary 'attributes' template variable excludes some module attributes

Open
#8,182 2 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autosummary type:bug
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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.