I think agree with those changes. pyplot has two versions in the API list. I don't believe this pr fix that. edit: ok it did.

One thing I have thought about is that I think that it should be clearer that pyplot include functions for starting ploting (it was clear in the new version) and functions that works on several figures or more general that do not exist somewhere else, plt.figure. plt.close, plt.ion(), plt.show(), etc. So it is not just functions that easily can be avoided with the OO API.

Hm, apparently I cannot link to the documentation in api/_as_gen (I.e. stuff generated by autosummary via gallery). Then, I’d still need a second function list for pyplot - not cool. Or, alternatively I‘d have to remove or replace the pyplot top level menu entry altogether. As written above, the pyplot menu entry is debatable, but I had originally planned to discuss that later.

Do you do the pyplot autosummary somewhere in the documentation now?

If I understand this correctly, the pyplot autosummary is created by sphinx gallery.

I might misunderstand the issue but I put the link in the toolbar with the master version of everything else and it did work (I first deleted all pyplot files in api/_as_gen).

I don't understand all details with automodule, autosummary etc but I don't think anything is created by sphinxs by default. One thing that confused me was that you can get strange result if you don't delete the files in the _as_gen folder if the you change the structure of the documentation (I didn't understand why the links to methods in the Axes class suddenly was to a huge Axes class file and not to a file for every method as it usually are in the documentation).

I don't completely understand the mechanism either. I did some adaption so that it now works at least. See Summary above.

I find the "Pyplot function overview" page rather chaotic. What is the difference to the pyplot module docs, what is matplotlib.pyplot.plotting() (does that function exist, and if so for what purpose?)?

On the same page there is a "Colors in Matplotlib" section. What's the relation of "colors" to "pyplot"? Why have that on the same page having nothing to do with pyplot, but being in itself quite informative? I guess this should get its own page and toc link somewhere?

In total why does this pyplot_summary page exist? The Modules toc should directly link to matplotlib.pyplot's module doc page, just as the "pyplot API toc" does.

@ImportanceOfBeingErnest Your're with the "Pyplot function overview" page. It rather collects the weird stuff from https://matplotlib.org/api/pyplot_summary.html and https://matplotlib.org/api/index.html (see the pyplot reference at the bottom of the page).

I didn't manage to get these resolved so far. Somehow we need this pyplot autosummary - otherwise the real pyplot function list is not created. I've now just put in a less public place - only accessible via "The Matplotlib API" -> "Modules" -> "Pyplot function overview". The more accessible places now link to the new "API overview" which in turn links to relevant function lists of pyplot and Figure and Axes.

You are right, that this "Pyplot function overview" page has to go at some point. However, we need to find a way for the autosummary and a place to put the color docs (possibly rewrite). It's a bit of work to be done there, which I would like to defer to other PRs.

To me, this PR is making things a little less awkward, or at least less obviously awkward. As such it's an improvement and may go in as is. Further improvements should go into additional PRs.

Yes, I'm all in for the changes. One drawback I see is that the individual modules have been moved one click further away from the homepage. It might be even more difficult to find let's say the matplotlib.transforms module now -- now you have to know that you need to click on the "modules" first and that "modules" link is really hidden between like 30 other links in a long list.

I agree, that it's suboptimal to have this one level deeper. OTOH to be honest, I wouldn't go through the structure anyway but use the module index or the search instead.

And the previous solution of having module names right next to "Toolkits", "API changes" and "Colors in Matplotlib" is structurally worse than the proposed change.

Yes, the proposed change is definitely for the better.

In general I think the current documentation (and its structure) are very good for people who already have a little experience with matplotlib and know what to look out for.
For newcomers (new to scientific python or maybe just new to matplotlib) the documentation is not very easy to walk through.

I would suggest to make a standard pyplot_api.rst page where the module is either downloaded with automodule or auto-summary instead of the pyplot_summary page.

Set the color section in its own colors_api.rst file.

I think that the list that is the result of the pyplot.plotting function is very confusing (at least on its own). It is very easy to believe that it is a list of functions of the full pyplot module when it isn't. No reason to have two pyplot pages.

I would also suggest to have the api/index.html in the toolbar.

I believe that this structure is possible to achieve but I don't understand all details with automodule and autosummary. One problem might be that I believe that you need to list all functions by hand in the standard auto-summary structure but that you don't need that if you use :autofunction: but that function make a link to a new page that is probably not that good.

The whole API list is not that consistent. The animation_api.rst is for example more a tutorial than a api reference.

@fredrik-1 totally agree, but can we make one step at a time? We won't get all this sorted out quickly. And I would like to get at least the partial improvement I've done here into 3.0.

@Carreau You can add @NelleV to the list of users 😅 Although being bitten by it yesterday, I try to stop…

We still have a couple of
active users (fperez and gaelvaroquaux) so still keeping it around

if only we knew some some people who knew @fperez and @GaelVaroquaux to talk to them .... 😈

But seriously, we can never deprecate pylab (there is the hope it eventually bit rots, no one notices and then 3 versions later we drop it but given that it is mostly import statements that seems unlikely) because it was too widely used (because it was widely advocated for a time).

I would rather just not talk about pylab in the docs at all (that was the consensus we came to the last time this came up). Saying "Please don't do X" still tells a new user "You can do X". No one believes you when you say "this looks like it makes your life easier now, but will make it harder later" (that is assume they read /listen past the 'but').

There is one evil plan which is to sleep(log(datetime.now()-RELEASE_TIMESTAMP) or similar at import time. It will using pylab a tiny bit more annoying each time.

@tacaswell In particular because pylab was/is widely used we should have a clear statement not to use it. Being silent about it rather leaves current users in the dark. Users will get pylab codes snippets somewhere. If pylab does still work and is not found in the docs, it will just be seen as incomplete documentation.

IMHO the API overview is the right place for this. All other occurences in the docs should be eliminated. I'm happy to change the wording to to whatever it takes to get the message across, e.g.

• Move the warning box directly below the section title (first read not to use it).
• Remove the from matplotlib.pylab import * import ideom (if people don't see how it was used it's more unlikely that they will pick it up).
• Maybe replace the "deprecated" note in the section title by "pending deprecation" if we cannot/do not want to deprecate it. By me it would also be ok to keep the "deprecated" or "pending deprecation" for an arbitraty long time.

How about officially deprecating pylab in the code? It doesn't mean that we'll remove it any time soon (/ever), but that's a clear indication to users who are still using it that they should not and means we don't have to document pylab anymore.

We got ourselves into trouble with 'deprecated but no removal date set' not being well documented, then _cntr went away, a bunch of stuff so broke and there was some frustration. I am a bit wary of getting into that situation again.

By officially deprecating do you mean issue warning on import of the module? There is no actual code in pylab (it is a very long docstring and then imports).

If you know what you are doing (and don't expect sum to work on generators) then the import * trick is mighty convenient and I am not sure we want to be tsk-tsking power users. On the other hand there are some surprisingly passionate defenders of teaching new users in such a flattened namespaces and despite repeated attempts I have failed to budge some of them. I don't want to be warning and then have people teaching new users say things like "Oh, just ignore that warning". There is enough issues with users ignoring warnings we don't want to re-enforce that.

One significant down side of the "just don't talk about it" approach is that to document that we are not going to talk about it, you have to talk about it....

This is a very long winded way of saying that @timhoffm has convinced me that we need at least a paragraph about it.

Some what related, do we know who controls the scipy wiki as ( scipy.github.io/old-wiki/pages/PyLab ) is the first hit if you google for 'pylab' which is less than great...

I'm not suggesting removing code were the deprecation date has not been set (we had the problem with the finance module as well, which had been deprecated in the documentation, but not in the code, and someone tried to remove it without the proper deprecation cycle in the code).
But if we are trying to actively push people to move away from the pylab API, then deprecating the module in the way to go. Only documenting that it is deprecated will not be enough, as most people don't really read the documentation, specially long time users.

I was suggesting deprecating it officially in the code, without a deprecation date, and not removing it until at least the very long future and with at least two releases with the version number on which it would be removed. It also gives a clear message that we will not maintain tests, do bug fixes, or write documentation about this module. (We currently have comments such as "more cleanup is needed" in the pylab.py file that suggests we might put in more work into this).

The discussion on technical deprecation is a bit too much in the context of this PR. This is a bit of a special case of API, that we do not want people to use but possibly also do not want to take away from existing users. I'm fine with not formally depreacting pylab as of now as a coutsy to long-time users.

I've reworded the pylab paragraph a bit to make it absolutely clear that it should not be used. On the other hand, I don't use the term "deprecation" anymore because for now, I explicitly do not want to make a statement if this will be removed some time in the future.

For quick re-review:

https://10867-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/api/index.html

@tacaswell still want pylab gone, or can this go in? You have a big red X