sphinx-doc / sphinx-doc/sphinx
`:members:` option on `automodule::` is ignored when `members` is set in `autodoc_default_options`
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
Given a conf.py containing the following:
extensions = [
"sphinx.ext.autodoc",
]
autodoc_default_options = {
"members": True,
#"undoc-members": True, # Doesn't matter whether this is commented out or not
}
and a reStructuredText file like the following:
.. automodule:: somemodule
:members: func1
All of the members of the module, not just func1, will appear in the documentation.
How to Reproduce
git clone https://github.com/jwodder/sphinx-bug-20211006
tox -e docs
# Open docs/_build/html/index.html and observe that both `show_in_documentation()`
# and `dont_show_documentation()` appear in the documentation
Expected behavior
Only the members listed in the automodule:: directive's :members: option should have been documented, as the settings in autodoc_default_options are, as the name suggests, defaults and thus should be overridden by explicit :members: options.
Your project
https://github.com/jwodder/sphinx-bug-20211006
Screenshots
OS
macOS 11.6
Python version
3.9.7
Sphinx version
4.2.0
Sphinx extensions
sphinx.ext.autodoc
Extra tools
No response
Additional context
No response
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 issue with the referenced conf.py and reStructuredText automodule example by running tox -e docs, then inspect sphinx.ext.autodoc handling of :members: and autodoc_default_options. Done means an explicit :members: func1 option documents only func1, rather than every module member, while the generated docs in docs/_build/html/index.html match the expected behavior.
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
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 45/100