Why all the extra plt.show() calls? sphinx-gallery should show the figures under the block they were created in, and I always think it's better to just have one plt.show() call at the end when running examples locally so all the figures appear at once.

Ah, because if you don't SG put "Out: Legend(...)" in a yellow box after everything. I could just put semicolons I guess?

I'm +1 for semicolons as opposed to plt.show()

Hmm, except semicolons are a flake8 exception...

This commit drops the shows, adds ; and puts in an exception for the trailing semicolon. In exchange I got rid of the lines that were too long 😉 OTOH we never make this exception so I'm not quite sure what our policy is on it. I personally don't see what the big deal is, and it greatly enhances the readability of the examples. Maybe there is a SG setting to suppress...

I don't think we should add in the ; exception to flake8 just for this file. You could set leg = ... to capture the return, or change the capture_repr/ignore_repr
https://sphinx-gallery.github.io/stable/auto_examples/plot_3_capture_repr.html#matplotlib-output

https://sphinx-gallery.github.io/stable/configuration.html#prevent-capture-of-certain-classes

I understand in general we do not want semicolons at the end of statements, but in this case it serves a really useful purpose - it saves the extra useless and confusing output, or it saves a spurious plt.show, or it saves a spurious and confusing assignment. OTOH I won't object if someone has a way to suppress these via configuration. However, note that some of our examples want the output to show up, so it can't be global.

Owee, I'm MrMeeseeks, Look at me.

There seem to be a conflict, please backport manually. Here are approximate instructions:

1. Checkout backport branch and update it.

git checkout v3.5.x
git pull

2. Cherry pick the first parent branch of the this PR on top of the older branch:

git cherry-pick -m1 f091d46a8559178f9ddd99553bb5415476469f10

3. You will likely have some merge/cherry-pick conflict here, fix them and commit:

git commit -am 'Backport PR #21794: DOC: some minor fixes to the usage rewrite'

4. Push to a named branch:

git push YOURFORK v3.5.x:auto-backport-of-pr-21794-on-v3.5.x

5. Create a PR against branch v3.5.x, I would have named this PR:

"Backport PR #21794 on branch v3.5.x (DOC: some minor fixes to the usage rewrite)"

And apply the correct labels and milestones.

Congratulations — you did some good work! Hopefully your backport PR will be tested by the continuous integration and merged soon!

Remember to remove the Still Needs Manual Backport label once the PR gets merged.

If these instructions are inaccurate, feel free to suggest an improvement.

Owee, I'm MrMeeseeks, Look at me.

There seem to be a conflict, please backport manually. Here are approximate instructions:

1. Checkout backport branch and update it.

git checkout v3.5.0-doc
git pull

2. Cherry pick the first parent branch of the this PR on top of the older branch:

git cherry-pick -m1 f091d46a8559178f9ddd99553bb5415476469f10

3. You will likely have some merge/cherry-pick conflict here, fix them and commit:

git commit -am 'Backport PR #21794: DOC: some minor fixes to the usage rewrite'

4. Push to a named branch:

git push YOURFORK v3.5.0-doc:auto-backport-of-pr-21794-on-v3.5.0-doc

5. Create a PR against branch v3.5.0-doc, I would have named this PR:

"Backport PR #21794 on branch v3.5.0-doc (DOC: some minor fixes to the usage rewrite)"

And apply the correct labels and milestones.

Congratulations — you did some good work! Hopefully your backport PR will be tested by the continuous integration and merged soon!

Remember to remove the Still Needs Manual Backport label once the PR gets merged.

If these instructions are inaccurate, feel free to suggest an improvement.

I'm in favor of not backporting this and letting the examples start to diverge again.

This depends on #21641, which has not been backported yet. But that also conflicts, so I guess depends on whether @jklymak wants to do it.

I think we should back-port these, as the current Usage Guide is very sparse....

I understand in general we do not want semicolons at the end of statements, but in this case it serves a really useful purpose - it saves the extra useless and confusing output

I have no idea why, but the yellow output boxes are still present in the current devdocs Basic Usage tutorial, despite the semicolons.

Yes, that didn't work too well ;-)