Repository navigation
Improve matplotlib.axes documentation - #24769
tacaswell merged 1 commit into
Conversation
Sorry, something went wrong.
story645
left a comment
There was a problem hiding this comment.
I like the idea of this change but am being nit picky about wording 'cause this is sort of one of the most conceptually important things to grok. Maybe embed the anatomy figure if it's now its own page?
Sorry, something went wrong.
| 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)
Sorry, something went wrong.
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
Sorry, something went wrong.
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
Sorry, something went wrong.
j1642
left a comment
There was a problem hiding this comment.
Should "plotted data" and "axis ticks" be separate?
Sorry, something went wrong.
|
This has caused many duplicate entries, perhaps too much for GitHub to display. |
Sorry, something went wrong.
- 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>
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 (and is not of much use since the private _AxesBase does not have generated documentation. The only additional information is that it originally inherits from Artist, which I've now included as a sentence in the docstring.