A downside of this - and I just realized that we already have the issue for Axes - that all code links `.Figure` go to the sub-page, whereas logically it would make more sense to have them point to the index page.

I have no idea how to improve on this with existing means (well, one could introduce a custom directive :c:`Figure` , but (i) I'm reluctant to give up on the simpler formatting of `.Figure` and (ii) since that is a non-standard appoach, it's likely that new standard refrences `.Figure` will keep creeping in.) I've opened an issue to sphinx. Maybe we have to live with that for now.

I see what you are saying, but I'm not convinced it is a huge problem:

`matplotlib.figure` is the right way to get the overall index if that is what we want in the docs.

`.Figure` takes us to the instantiation docs, which I think we do not want in the overview.

At least on non-mobile, the left-hand navigation and the breadcrumb is pretty clear where the module level description is:

An alternative may be that we make entries for matplotlib.figure.Figure and matplotlib.figure.SubFigure. We don't do this with any other APIs currently, but I don't think there is any reason they API reference has to slavishly correspond to files in the library directory. I think this would mean figure_Figure_api.rst and figure_SubFigure_api.rst, but that doesn't seem the end of the world.

Finally, an even more radical suggestions would be to rearrange the source code itself; eg have a subfigure module, and split FigureBase into its own private module. That doesn't seem the end of the world - I doubt many people are doing import matplotlib.figure.SubFigure yet.

So, I think the proposed change here is better than what we currently have, but I'm open to relatively major surgery if we can get something even better.

Thinking about this more though: even if we do the more radical suggestions above, I don't see how we get the init docs onto their own page and out of the intro.

Your suggestion to sphinx seems reasonable. Not sure how we emulate that internally.

One could try to separate class and init docstring, put the class on the overview page and init in subpage where the class currently is. May be possible through appropriate configuration https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration.

But that can be a follow up PR. I suggest to merge this as is for now.

I think a fair bit is possible with templates as well.

See newest version...

This is probably the silliest little nit but I wish this figure was a bit wider to match the text width.

The width of the figure is fixed at approximately 1/2 the maximum width of the text, so it would have to be twice as wide to match the text width. You must be looking at a thinner viewport.