sphinx
sphinx copied to clipboard
sphinx-doc
Attribute's are considered undocumented if described in the header
Describe the bug
Using autodoc, I am seeing that attributes are considered undocumented even if they are documented in the class header. This leads to duplicate entries as seen here:
An attribute should be considered documented if it's documented in the header.
How to Reproduce
index.rst file:
.. automodule:: test_sphinx
:members:
:undoc-members:
test_sphinx.py file:
class ExamplePEP526Class:
"""The summary line for a class docstring should fit on one line.
If the class has public attributes, they may be documented here
in an ``Attributes`` section and follow the same formatting as a
function's ``Args`` section. If ``napoleon_attr_annotations``
is True, types can be specified in the class body using ``PEP 526``
annotations.
Attributes:
attr1: Description of `attr1`.
attr2: Description of `attr2`.
"""
attr1: str = 'test'
attr2: int = 5
Environment Information
Platform: win32; (Windows-10-10.0.22621-SP0)
Python version: 3.10.9 (tags/v3.10.9:1dd9be6, Dec 6 2022, 20:01:21) [MSC v.1934 64 bit (AMD64)])
Python implementation: CPython
Sphinx version: 7.2.6
Docutils version: 0.20.1
Jinja2 version: 3.1.3
Pygments version: 2.17.2
Sphinx extensions
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
napoleon_attr_annotations = True
Additional context
No response
Seems to be the exact same problem as explained in this post.
In this case you have to think about both autodoc and napoleon working simultaneously and declaring the attributes twice in the rst. Arguably this isn't a bug but a feature, because the extensions are working as expected.
Seems to be the exact same problem as explained in this post.
In this case you have to think about both autodoc and napoleon working simultaneously and declaring the attributes twice in the rst. Arguably this isn't a bug but a feature, because the extensions are working as expected.
That post has some good insight, thanks! I didn't really think of it that way. I can potentially use that exclude-members workaround in various scenarios, although not ideal.
Doesn't this make the Attributes: tag redundant if I have to put a comment description on the attribute to mark is as documented? To me, it just seems awkward the actual docstring doesn't have priority for what is considered documented when it comes to documentation. Although this just may be me thinking of sphinx and autodoc as part of the same thing, when autodoc is just a plugin. I'll think on this, thanks.
Doesn't this make the
Attributes:tag redundant
No! The Attributes: docstring section still retains its intended functionality.
if I have to put a comment description on the attribute to mark is as documented?
The main way to achieve that is by carefully setting the options in the autodoc directives. There could be use cases where you wanted to mix:
- napoleon docstrings.
- with inline documentation comments.
- docstrings above or below each attribute declaration in the code.
- and explicit documentation in the rst files.
So that's 4 different ways that can coexist all at once, and Sphinx supports them simultaneously for flexibility and convenience.
it just seems awkward the actual docstring doesn't have priority for what is considered documented when it comes to documentation.
This could make sense, to have both extensions interoperate to mark members as documented if napoleon parses them in the docstring sections. However, if in an exceptional case you wanted the opposite behavior (I have a hard time imagining a use case) it would be necessary to add an additional option to the directive.