Improve matplotlib.axes documentation #24769
Conversation
lib/matplotlib/axes/_axes.py
Outdated
| @@ -46,10 +46,14 @@ | |||
| @_docstring.interpd | |||
| class Axes(_AxesBase): | |||
| """ | |||
| The `Axes` contains most of the figure elements: `~.axis.Axis`, | |||
| The Axes class represents one (sub-)plot in a figure. | |||
There was a problem hiding this comment.
I get the the original wording is a problem because a figure can contain multiple Axes, but I think represents is the wrong word here too since that implies some sort of abstraction but modifying an axes object modifies the corresponding plot.
It's something like "An Axes object encapsulates all the elements of an individual (sub-plot) in a figure" but we're sorta inconsistent about using plot to refer to the axes and everything it contains or to the semantic elements within the plot (plot types gallery)
There was a problem hiding this comment.
Changed to your suggestion. This is mainly a structural PR. The goal is to declutter https://matplotlib.org/devdocs/api/axes_api.html#module-matplotlib.axes so that it does not start with two screens full of unhelpful Axes constructor documentation.
There's still lots of room for content improvement. But I would like to defer this to another PR. IMHO the Anatomy figure has too much detail for the Axes context. I would like a "Parts of a figure" reference page that defines our terminology. This is part of the bigger discussion about kinds of documentation. A tutorial is not a reference point for such reference documentation. This is beyond
There was a problem hiding this comment.
I would like a "Parts of a figure" reference page that defines our terminology.
Agree that would be awesome
9a88fe7 to
dbad2d1
Compare
|
This has caused many duplicate entries, perhaps too much for GitHub to display. |
- Move the Axes class documentation to a sub-page. The constructor is quite lengthy and not needed by most users. - Add an introductory sentence to set the context for the subsequent listing and structure of the Axes methods. Note: I've removed the inheritance diagram, because it does not contain much relevant information. The inheritance from _AxesBase is shown in the class docstring as well. The only additional information is that it originally inherits from Artist, which I've now included as a sentence in the docstring. Co-authored-by: hannah <story645@gmail.com> Co-authored-by: j1642 <60148902+j1642@users.noreply.github.com>
340a517 to
4236f59
Compare
Note: I've removed the inheritance diagram, because it does not contain much relevant information.
The inheritance from
_AxesBaseis shown in the class docstring as well (and is not of much use since the private_AxesBasedoes not have generated documentation. The only additional information is that it originally inherits fromArtist, which I've now included as a sentence in the docstring.