Repository navigation
[Doc]: regression in stable/api/index #26623
Description
Documentation Link
https://matplotlib.org/stable/api/index versus https://matplotlib.org/devdocs/api/index.html
Problem
There was some cleanup of https://matplotlib.org/devdocs/api/index.html by @timhoffm in #26402, but I feel it went too far. For instance, there used to be a small plot on the API page to orient users as to the basic usage pattern. I find the current version very terse, and not helpful to new users. You can argue that an API page should be terse, however our API is actually pretty strange and subject to confusion, so I think getting users on the right path here is helpful.
Suggested improvement
- should at least include the small example again
- be a bit more verbose about the two APIs.
- include
subplot_mosaicon the same level assubplots.
Activity
story645 commentedon Aug 29, 2023
I'd rather just have a very large link at the top: to learn how to use this, see quick start/user guide.
I kinda think the teach by example isn't much better than the stack overflow cause it's still missing contextualization of concept. And if we were gonna do contextualization on the API page then it should be happening within the explanation of each API and not before.
jklymak commentedon Aug 29, 2023
The original goal of the simple example was to provide a quick map of the API - create a Figure and Axes, use the Axes. Previously there was nothing to guide users to the Axes page. The current version does that using words, but those words are pretty abstract if you aren't familiar with the library.
timhoffm commentedon Aug 30, 2023
If you aren't familiar with the library, the API reference should not be your starting point. We redirect such people:
and if you will, add @story645's proposal
jklymak commentedon Aug 30, 2023
By that logic there should be no discussion of the two API types here at all, which we decided quite a while ago was untenable.
story645 commentedon Aug 30, 2023
The basic discussion was there to signpost/roadmap where people need to go when they hit the landing page. Including folks who've learned a ton of pyplot via examples so may not know the name of what they're using but can pattern match to it -> which is why I think a teeny tiny no picture need code example could be useful.
jklymak commentedon Aug 30, 2023
What is the rationale for not showing the picture that results from the code? Clutter and succinctness doesn't make sense, because there is nothing else on the page.
story645 commentedon Aug 30, 2023
Because the goal here isn't to show what the code produces, but to highlight the differences in API. So the worry, especially if there's a lot going on in the figure, is that the figure contents will distract from the code.
Granted, I'm OK with teeny tiny can fit in table stripped down figs that show that these interfaces yield the same thing.