Restructure interface section of API Reference index page #26402
Conversation
doc/api/index.rst
Outdated
| ^^^^^^^^^^^^^^^^ | ||
| Examples: | ||
|
|
||
| `matplotlib.pyplot` is a collection of functions that make | ||
| Matplotlib work like MATLAB. Each pyplot function makes some change to a | ||
| figure: e.g., creates a figure, creates a plotting area in a figure, plots | ||
| some lines in a plotting area, decorates the plot with labels, etc. | ||
| - Most :ref:`examples <examples-index>` use this | ||
|
|
||
| `.pyplot` is mainly intended for interactive plots and simple cases of | ||
| programmatic plot generation. | ||
| (except for the pyplot section) |
There was a problem hiding this comment.
I don't think you need this, and for a general audience I'd maybe just point to the plot types gallery and the new user guide examples
There was a problem hiding this comment.
I was a bit bolder now and removed the exmaples here completely. This page is the API reference and serves the purpose to navigate people to the relevant parts of the API docs. The different interfaces are only relevant here to the extent that people know the rough context whether they want to go to Axes or pyplot. The focus is on API lookup, not on learning. Therefore, I don't think example links are needed here. - And I have to say, I really like the now compact version better.
There was a problem hiding this comment.
I think if you want to go even more compact, you can probably incorporate the info in the bulleted list into the bottom of each grid cell and then remove the list all together.
e272b5c to
bab0b5b
Compare
- switch to Axes interface / pyplot interface terminology (matplotlib#26388) - Reduce the interface description to very compact two-sentence descriptions and refer to the interface page for everything else. The focus here is to point the users to relevant API resources for the respective interfaces, not to discuss these interfaces in detail. The latter is the task of https://matplotlib.org/devdocs/users/explain/figure/api_interfaces.html and I will add some missing pieces there in a follow-up PR. Co-authored-by: hannah <story645@gmail.com>
bab0b5b to
49b2728
Compare
|
|
||
| API: |
There was a problem hiding this comment.
| API: | |
looking in the rendered docs, it totally doesn't need it.
switch to Axes interface / pyplot interface terminology ([Doc]: Revisit interface terminology: Axes interface / pyplot interface #26388)
Reduce the interface description to very compact two-sentence descriptions and refer to the interface page for everything else.
The focus here is to point the users to relevant API resources for the respective interfaces, not to discuss these interfaces in detail. The latter is the task of https://matplotlib.org/devdocs/users/explain/figure/api_interfaces.html and I will add some missing pieces there in a follow-up PR.