I'm not a huge fan of this syntax, versus justfig, axs = and then settingax = axs[row, col]. But not a show-stopper at all.

I'm with you on that. We do it both ways. And while I think consistency is good, maybe showing options are important too

I'm not huge fan of putting arrays in variable names (ax1, ax2, ax3, ax4) rather than just the type (ax[0]). The former is so much harder to change later on, so I'm not sure we should actually be promoting it. If the row/column nature is a problem, you can always doax = ax.flatten(). My $0.02.

Why not reuseCS?

My thought (which is behind e.g.,fig1, ax1 as well) is that I want it to be completely clear to a totally "n00b" (to programming, python, or matplotlib) that we're starting over and working on something new.

I don't think you need thestr here. set_title does that as well...

When I looked at the rendered page, theNone plot has no title, but in the current docs, is does have a title that says "None"

Oh, yes, I guessNone might have a different meaning. Fair enough

Not a fan ofaxes becuase of the plural/singular ambiguity....

fair point

super minor - I'd only change if someone else has serious issues...

Sincefig, doesn't have a number,axes1 shouldn't either.

I propose to decide on one canonical way of writing the second argument:axs vs.axes. Both seem to be used. I slightly tend toaxs in the sense of multipleax. Since Axes and Axis are both class namesaxes may just too easily be misinterpreted as multipleAxis or a singleAxes instance.

So proposed value here isaxs.

line is not used afterwards, so it should be left out. Same with the return values on the following line.

I'm going to push back on this a bit. My gut feeling is that users -- especially new users -- are more likely to read these example than the docstrings.

So I think we should use this examples to be as explicit as possible about what each method is doing.

There are a lot of questions on SO along the lines of "how do I get an artist that's on my plot". While, there's a decent way to do that after the fact, I think it'd be nice to get users in the habbit of capturing things sooner rather than searching for them later.

I'm 100% with you that users are learning from the examples. Therefore a big 👍 for updating the examples.

My conclusion from learning by example is that the examples should be similar to real-world uses. I fear that if all the examples hadline = ax.plot(x, y), you'll find a lot of people having exactly that in their scripts, even if they don't useline at all - at least that's my experience with less-experienced users.

I'm fine, if you want to keep the return values onspecgram(). That's what the example is about. If so, it would be good to move the related comment from a few lines above directly to the function call. Something like:

Pxx, freqs, bins, im = ax2.specgram(x, NFFT=NFFT, Fs=Fs, noverlap=900)# returned values:# - Pxx: the periodograms# - freqs: the frequency vector# - bins: the centers of the time bins# - im: the matplotlib.image.AxesImage instance representing the data in the plot

However, since this is not aboutplot(), I wouldn't add the unusedline.

Well said. I'm on aboard.

Unfortunately sphinx references don't work in code comments. See theresulting file.

I'll leave it up to you, if you want to keep it anyway.