astropy / astropy/sphinx-automodapi

Inherit docstrings for class attributes

Open
#55 3 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.