BTW ping @rougier as I think you made the original. If you want to have a go at updating this, I'm sure no one would object!

Here is another version from the latest commit that adds some code. A bit messy for review, but for discussion if better or worse than the simpler version:

I like it a lot. However, if you're going to mention ax.scatter, I think you should actually have some variation either in size or in color (if you're just using the same marker everywhere I'd rather encourage people to use plot for that).

I agree that ax.plot would be better, and indeed that is what is used in the code. OTOH,for maximum info content, it seems better to reference scatter, and I'm somewhat reluctant to make the plot more complicated.

Well strictly speakting, this mostly shows the anatomy of an Axes, not a Figure. Maybe we can have a plot "Anatomy of a Figure" showing two Axes (subplots) and a Figure title (maybe also wspace) and another one "Anatomy of an Axes" like the one above but with just one curve with markers?

Also maybe it's worth to denote the Axis with a big rounded rectangle including the ticks and tick labels instead of the circle, otherwise it's a bit unclear how an Axis differs from a spine.

Just a concept, needs to be fine tuned and the additional figure text and the axes legends etc. maybe too confusing and the color is certainly not optimal (the left Axes color = the right Figure color to show correspondence). The main idea was to show what belongs to a Figure and what to an Axes.

(code see this gist)

I thought of using colors, but then the little circle illusion becomes confusing rather than helpful. Certainly one could come up with other versions of this, but it is a venerable figure, so I was loathe to change it too substantially.

I would vote to stay with "Anatomy of a Figure". Everyone knows what a "Figure" is, whereas "Axes" is more jargonny, and indeed part of what this figure is meant to demonstrate.

I'd also say, let's stick to this style-updated version of the current figure for now. We can always make further changes later.

Merged. There has been enough time to speak up against this.

AArrg, too late but:

• why change the discs for squares?
• why italics?
• why making the circle linewidth so strong?
• some of the cicles are not centered on what they are suposed to show
• why the mono serif font ?
• circles should stay black

Its not particularly too late, this is only in the devdocs so far... Ooops, sorry take that back, I guess it is in the current examples. But I think that is obscure enough that it is easy to change.

AArrg, too late but:

• why change the discs for squares?
• why italics?
• why making the circle linewidth so strong?

These were just aesthetic choices. But I'm not trying to claim I have any taste, just the very old version was outdated.

• some of the cicles are not centered on what they are suposed to show

Yes, I can see a few of them are a bit off

• why the mono serif font ?

To indicate that it is code?

• circles should stay black

Aesthetic choice again - I thought it useful differentiate the plot elements and the annotations.

I would prefer to minimize changes for a first update and the we can discuss further changes. Obviously my aesthetic choices are a bit different than yours (and it's fine) but I would prefer we dicuss them a bit more before making changes.
Different font for code is a good idea indeed, my question was related to the serif choice. As for circles, I would either keep them black or chose a color different from the line plot (else, it suggests an identical semantical meaning, sort of).

Sure, well lets just revert, and consider this an open issue that the old version could use some freshening.

I agree that figure need some update. Let's start with the updated version and check if we can change this or that aspecT.

This is definitely your figure, so happy to approach it how you would like!