marked as WIP, since I imagine this isn't ready for review yet?

Itseems we shouldn't have to change the doc tree to get this to work, but I've not looked too carefully. It seemed to me that the index.rst fordoc/mpl_toolkits/axes_grid/index.rst just wasn't formatted in a modern way. But I didn't get to the point of testing so I could be wrong.

This is not yet ready for review in the sense of a working code; and I suppose tests will fail. But the docs can be built without-W flag, i.e.SPHINXOPTS=. In that sense, if anyone wants to comment on this, they should.

The problem of keeping the doc/mpl_toolkits is that what is in there can hardly be synchronized with the rest of the docs. While if you put it into doc/api/... it can live there without problem.

The problem about missing files seems to be due to sphinx-gallery not creating.examples files for aliased classes. I opened issuesphinx-gallery/sphinx-gallery#365 over there.

The colorbar problem is however a real mystery. If I rename thempl_toolkits.axes_grid1.colorbar.colorbar method todonaldduck, the respective doc page are created without problem (this just breaks some of the examples of course).

The last blocker here is that it is apparently not possible to get an autodoc/autosummary documentation created for a file that contains a class and a function of the same name, one uppercase, one lowercase.

class Colorbar():      # ...def colorbar():     # ...

I opened this issuesphinx-doc/sphinx#4874 about it.

I bet the issue will be closed as wontfix on sphinx, as it's a fundamental problem of the Windows FS (that it doesn't distinguish (*modulo really low-level hacks) files differing only based case; and any fix I can think of would involve breaking the correspondence [pythonname] -> [pythonname.rst] -> [pythonname.html], which seems to be quite a big price to pay).

Looks like the stuff builds fine on circleci, so that's good enough for me (but leaving open for now in case anyone wants to comment on the above).

@anntzer I doubt the version as it is now will be the version going in. I wanted to share the current progress because I got stuck at several places and thought maybe someone has a good idea.

Now it seems that it finally passes the test on the server. 🎉
But I cannot build the docs correctly on windows. Not sure in how far this is a blocker, like "You can build the docs only on linux." is not really statisfactory, right?

The next thing to look at is of course how the toolkits should finally look like. Feedback and suggestions are welcome.
This is the current version.

• Should there be a list as it is now?
• Should the axes_grid disappear completely in favour of axes_grid1 and axisartist?

What do you get on Windows? A complete failure to build (even removing -W from sphinxopts), or just something wrong wrt colorbar links?
If the latter, I wouldn't consider that a blocker because solving casefolding issues on Windows is well beyond what Matplotlib should be worried about (see e.g. the issues for git and mercurial on that same topic). If the former I'd be more agreeable to waiting for a fix.

After the config changes get reverted, this is great. Great job@ImportanceOfBeingErnest this is a huge improvement!

Without-W flag, i.e. turning errors into warnings, you get a lot of red lines in the console when building but the output is fine, except for the .colorbar module and any links to or from it.
In that sense maybe you're right and one would just have to include a sentence about removing-W on the page about building the docs on windows.

I will try to get a good version of this together tomorrow - there is still a lot of pieces to glue together.

I would just remove the -W from make.bat then, with a comment explaining why.

To be clear, I think Windows support is just as important as Linux/OSX (see#3148 for literally my first issue (not PR) on this repo), but the specific issue at hand is so complex that it's just not worth blocking on it.

I think I found an acceptable workaround, not using the autosummary for the colorbar docs at all. This allows to keep the-W flag.

I think this should now be ready for review.

Milestoning 3.0, but happy for it to be back ported if possible...

Yes,.Axes wont work any more. But I suppose~.axes.Axes would (as commented by@dstansby). I could change them all to~.axes.Axes if people want that.
I did changeall occurences, so you don't need to be afraid of that. Essentially if we keep the-W flag active, that will be an automatic test. If someone puts~.Axes somewhere the doc built would fail with a rather self-explanatory error in how far this is ambiguous. (Unfortunately the error will tell you the line in the rst file, not the python file where this happens, so one might need to search for a bit to find the offending line.)

@tacaswell This is the PR I was refering to, which revives theaxes_grid1 andaxisartist documentation. The respective docs had been present in v2.0.2 seee.g. this page

But then it has disappeared, such that thecurrent 2.2.2 version looks pretty empty.

This PR has revived the documentation. In that sense it fixes a regression. One could therefore argue that it should be backported.
Of course one could also argue that it is non-critical because there is still the 2.0.2 version available from the internet in case people need it.

@meeseeksdev backport to v2.2.x

There seem to be a conflict, please backport manually

This can't go back to 2.2.2-doc due to the changes to the source files, lets see if it backports cleanly...