Fix #8180: Docstring metadata ignored for attributes #10447
Closed
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Feature or Bugfix
Purpose
:meta private:
#8700 and Autosummary does not respect autodoc's :meta public: #8922Detail
:meta private:
and:meta public:
for functions and module variables.autodoc.Documenter.filter_members
does not see the docstring of class attributes. Therefore the fix must make the docstring available. For variables of a module ("global variables") the docstring is stored inObjectMember.docstring
(seeModuleDocumenter.get_module_members()
).autodoc.Documenter.filter_members
retrieves the docstring from the ObjectMember object. For class attributes, the ObjectMember does not contain the docstring, becauseautodoc.importer.get_class_members
does not set it, when it creates the ObjectMember object. My fix changesautodoc.importer.get_class_members
to set the docstring.autodoc.Documenter.filter_members
. This patch also fixes the bug, but is makes the information flow more complicated. Currentlyautodoc.Documenter.filter_members
uses just two ways to get the docstring of a member: as the result ofsphinx.util.inspect.getdoc
or from ObjectMember.docstring. The patch would add a third way: usinganalyzer.find_attr_docs()
.Relates
:meta private:
#8700 and Autosummary does not respect autodoc's :meta public: #8922: autosummary also usesautodoc.importer.get_class_members
. Therefore, if autosummary shall respect metadata, it needs the docstring.