can this go in annotate since this is also about labeling?

This is such a bizarre API I hesitate to add it at all. This should be part of the Axes API and has no business on Figure.

maybe so, but I think putting it in it;s very own section inadvertently gives it more attention

OK, done - not a huge fan, but its innocuous enough.

I think this maybe needs a sentence on what is the difference? I'm seeing the (sub) throughout here and am very confused on which when why

Changed to:

Every visualization starts with a `~.Figure` class, often instantiated via `pyplot.figure`, `.pyplot.subplots`, or `.pyplot.subplot_mosaic`. Matplotlib has the concept of a `~.SubFigure`, which is a logical figure inside a parent `~.Figure`.  Most common methods are defined in `~.FigureBase`, but there are a few methods that only make sense on the parent `~.Figure`.

let me know if that is any clearer

Mostly clearer thanks, though I think instead of logical figure maybe subclass might be clearer.

This is now under Subfigure

SubFigure=========Matplotlib has the concept of a `~.SubFigure`, which is a logical figure insidea parent `~.Figure`.  It has many of the same methods as the parent.  See:ref:`nested_axes_layouts`.

Probably sick of hearing this from me, but this is my usual concern that this is doing both too much and not enough - what I mean is that it feels like it's trying to show off some of the capabilities of the figure creation (like the width kwargs) but it's also not comprehensive. If there must be code (and I don't think there should be) then I think it should be at a consistent level: here is how we create figures, here is how we create subfigures - here is us showing how to use one method on both objects, and then "to learn more about this, see user guide

This code is not shown by default, though of course the user can download it if curious. The goal is to visually orient the reader as to what a Figure is versus a SubFigure.

I like visuals, but feel this is disproportional here. While SubFigure is an advanced concept that is maybe relevant for 10% of our users, the plot draws more attention to SubFigure than to Figure.

It's good that the code is not shown. I'd even claim it's not needed at all: People don't need to know how to create that figure exactly. To learn how to do SubFigures, they should go to the linked docs.
I suggest to reduce this even further to a conceptual graphic, like we're doing for the Axes creation in#26417:

While SubFigure is an advanced concept that is maybe relevant for 10% of our users, the plot draws more attention to SubFigure than to Figure.

Fair enough - the cross linking issues were such that this had to get moved down to the bottom of this page anyways.

It's good that the code is not shown. I'd even claim it's not needed at al

I'm not a fan of using graphviz or creating standalone svg's to document Matplotlib's graphics features...

This visual is now under Subfigure.

Obviously we disagree on whether such signposts are helpful. I suppose someone else will have to decide.

consistent voice in titles?

Fixed all the titles - removed redundant "Figure" from them...

A downside of this - and I just realized that we already have the issue forAxes - that all code links`.Figure` go to thesub-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 anissue 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 donot want in the overview.

At least on non-mobile, the left-hand navigationand 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 meanfigure_Figure_api.rst andfigure_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 splitFigureBase into its own private module. That doesn't seem the end of the world - I doubt many people are doingimport 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 configurationhttps://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...

slight nit that I think this tends to be common usage so folks are more likely to parse quickly

Except then the voice would be inconsistent.

hmm - Interactivity acts like a noun like layout rather than a verb like annotating, so it's still consistent?

OK, changed to "Interactive", which is what's used for all the other API pages (for better or worse). We can search and replace to "Interactivity" if that is better as a follow-up, but at least now it's consistent.

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.

hmm - Interactivity acts like a noun like layout rather than a verb like annotating, so it's still consistent?