Repository navigation
[Doc]: Improve API documentation of attributes #22897
Description
Documentation Link
No response
Problem
We currently have to resort to literals, instead of links
- ax.transAxes / transAxes
- ax.dataLim
- ax.fmt_xdata / ax.fmt_ydata / ax.fmt_zdata
- Axes.lines
- axes.bbox
- figure.bbox
- cbar_axes
Suggested improvement
We should have API documentation for this, and it should be referencable in sphinx.
What needs to be done:
Figure out how this could be done. Note that some attributes are documented, but cannot be referenced (e.g. dataLim https://matplotlib.org/devdocs/api/axes_api.html#the-axes-class), while others don't have a documentation at all.
Activity
mwaskom commented on Apr 26, 2022
I think one (the?) way to get "documented attributes" is to make them properties, then sphinx autodoc will pick up the docstring. I am not sure whether cross-references work there, but I'm not sure why they wouldn't.
timhoffm commented on Apr 27, 2022
Properties would work. However, I'm reluctant to add complexity and overhead to the code only to get documentation.
One can add attribute documentation to the class docstring in numpydoc. And we sometimes already do that. The problem is that one cannot link to these. While that should in principle possible in sphinx, it does not work for us. Maybe the Attribute section of numpydoc does not get translated to a .. py:attribute:: directive. There's probably something broken either in numpydoc or in sphinx under the hood.
This is something to be investigated and likely needs to be adressed upstream.
Independent of this, we should start to consistently document public attributes as well.
timhoffm commented on Sep 26, 2024
As a matter of fact, the entires of the Attributes section do not contain link targets. (This could be discussed upstream, but I suspect, we'd need to contribute for a change here since classes are not that heavily used/documented in numpy)
An alternative approach, which may be reasonable for larger classes is attempted in #28825:
T.b.c: Does this also work with doc comments? (self.attr = 1 #: A doc comment for attr)