Inherit docstrings for class attributes

[embray]

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:

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.

[hamogu]

:+1:

[pllim]

Sphinx now does this natively but doesn't seem to work with automodapi? https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_inherit_docstrings

[pllim]

If I set autodoc_inherit_docstrings = True in conf.py and use autoclass, it works, but not with automodapi.