astropy / astropy/sphinx-automodapi
Inherit docstrings for class attributes
- Dominant language
- Python
- Stars
- 67
- Forks
- 48
- Avg merge
- 11h 52m
- Merged PRs (30d)
- 1
Description
Sphinx provides a mechanism, which is not normally supported in Python, to provide docstrings for class attributes and module-level variables. We use this in several places in Astropy to document such objects. The syntax places a docstring immediately after the variable/attribute is defined like:
``` python
answer = 42
"""Answer to the question of life, the universe, and everything."""
```
Sphinx can pick these up and add docs for the `answer` variable to the documentation for whatever module or class it's defined in.
Astropy has a metaclass called `InheritDocstrings` which allows subclasses to automatically inherit docstrings from their base class for any members they override (and for which they do not explicitly provide docstrings). However, this mechanism doesn't work for class attributes since there isn't any officially supported way to handle them in Python. And would be nice to write a Sphinx extension and/or patch to Sphinx to make this work properly.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reading the InheritDocstrings metaclass and Sphinx's existing handling of docstrings for class attributes and module-level variables. Determine whether the work belongs in a Sphinx extension or a Sphinx patch, then define completion as inherited documentation appearing for overridden class attributes without explicit docstrings.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100