I think this might be a good place to restate the conceptual difference between a figure and an axes to help folks sort if they want to add more subplots to a figure or create a subfigure w/ a batch of subplots

Added an example, which if we are going into why to use subfigures, seems the easiest way to explain it.

I think something got garbled here

This was an explanation as to whatdpi means.

Oh sorry didn't mean to delete, just meant to flag that "to make you figures" was probably a misprint

Yep caught that one I think

I think this is misleading, the tracking is automatic and can not be opted out of.

It can be opted out of when you don't use pyplot, can't it? I'm not quite following your concern here.

We should define what a figure is. Maybe something like

In matplotlib, a~.Figure is the logical container for all visual elements. Think of it like a blank sheet of paper.
To add content, you'll add visual elements (called.Artist\s) to the figure though specific functions.

This is somewhat informal, but should give a rough mental model.

I think thats what the first two sentences below the example were meant to do?

When looking at Matplotlib visualization, you are almost always looking at
Artists placed on a~.Figure.

Has too little emphasis onFigure.Matplotlib visualization andArtists are mentioned first and are the syntactic objects in the sentence.Figure is only mentioned as the context ofArtists. I would like a sentence that hasFigure as the subject, like "A Figure is...". Also, I think this should come before any plot to set the scope/expectation. The plot code already has a lot of details and the user does not know what the relevance of the plot/shown code is.

As below, readers are unlikely to hit this page with no context. They will have seen matplotlib visualizations, even if only on the landing page. And the title clearly indicates that this is about Figures. We need to put a figure in context of what they have seen before so I prefer to mention that first.

Maybe add first

    fig = plt.figure(figsize=(2, 2), facecolor='0.8')    fig.text(0.1, 0.5, "This is a figure")

to illustrate the basic conecpt of adding content with out the need to already dive into theAxes / subplot complexity.

And then follow up with the Axes discussion.

I'm not in favour of adding a relatively obscure artist to the first example - an Axes is what 99.99% of visualizations start with. I personally wasn't even aware that Figure has a text method, so it's pretty obscure.

Though this inspires a new section below on adding artists....

I'm trying to make a minimal illustration of a figure. Maybe even

plt.figure(facecolor='lightblue')

is enough.

Side-remark: Please don't use the somewhat obscure '0.8' greyscale notation in a basic example. That is unnecessarily confusing.

If the empty figure is too little, you could usesuptitle(), which is simpler thantext():

plt.figure(facecolor='lightblue')plt.suptitle('This is a figure')

I want a minimal typical example of a figure in the context of what the reader has likely seen before, not an artificial example with nothing on it. Readers are not starting with zero context here.

I can easily change the background colour.

Updated to change the color and added some annotation on the Axes.

I want a minimal typical example of a figure in the context of what the reader has likely seen before, not an artificial example with nothing on it.

I would agree for a tutorial. In explanations however, I think we should clearly isolate the figure. Both visually, and from the code complexity

fig = plt.figure(facecolor='lightblue')fig.suptitle('This is a figure')

is much clearer than

fig = plt.figure(figsize=(2, 2), facecolor='lightskyblue',                 layout='constrained')fig.suptitle('Figure')ax = fig.add_subplot()ax.set_title('Axes', loc='left', fontstyle='oblique', fontsize='medium')

Readers are not starting with zero context here.

Again, I think this initial example is more effective in the context of something the viewer would have seen - 99.9999% of figures have an Axes. The complexity is all in separating the two objects in code so that the reader can understand how Matplotlib differentiates them internally. I don't feel that an empty figure is a good use of space or the reader's time.

I beg to differ.

in the context of something the viewer would have seen - 99.9999% of figures have an Axes.

Note also thatplt.figure(); fig.add_subplot() is rarely used (plt.subplots() being far more common and IMHO recommended). There is value in using the figure() call here explicitly and I'm not suggesting to change, but this fact weakens the familiarity argument. The generated figure is familiar, but the associated code is not.

I have the feeling that the current approach is neither fish nor fowl. Maybe, if you wan't to start with the familiar, really do subplots() and then explain that this does the two statements under the hood.

I really appreciate your work on the docs, and I'd like to make sure they are of maximal use for a diverse audience. I would like to encourage to carefully consider how the descriptions work for users with different backgrounds. We as authors have a very good understanding, but throwing in variations (add_subplot vs subplots) or concepts (In the text Artists are mentioned without explanation or a link for context) can be obstacles for some readers.

Unfortunately, I don't have much time currently. So I will withdraw from the PR and the discussion.

Continuing the discussion from#24999 (comment)

we only use pyplot for the first purpose, ...

That reads to me like "In the above example we are not adding the figures to the global registry". Maybe something like:

OK, I understand now. If we digress like this, I made it a bit more wordy:

By far the most common way to create a figure is using the:doc:`pyplot </tutorials/introductory/pyplot>` interface. As noted in:ref:`api_interfaces`, the pyplot interface serves two purposes.  One is to spinup the Backend and keep track of GUI windows. The other is a global state forAxes and Artists that allow a short-form API to plotting methods. In theexample above, we use pyplot for the first purpose, and create the Figure object,``fig``. As a side effect ``fig`` is also added to pyplot's global state, andcan be accessed via `~.pyplot.gcf`.

Super picky word choice preference, feel free to disregard:

Thanks, for some reason I had my spellchecker off, but now its on again ;-)