General comment, not sure if it's in scope here: the example figures seem to be unrelated to the code snippets in some cases. That's a bit confusing/distracting. Would you be willing to update?

Would you be willing to update?

Absolutely if you're willing to flag 'em.

@timhoffm , @jklymak , @QuLogic is it better than what was there enough yet?

@madphysicist can you open an issue about which figures don't match which code? Or if not, let me know and I'll do it. I wanted to do it here but honestly lately this tutorial seems to be getting touched a lot and I don't know how many more times I want to rebase. 🙃

@story645 Looks like the only place on this page with a discrepancy is the ConnectionPatch section towards the end. What I did not realize at the time is that you can click on a figure to get the code to generate it, so you can probably just ignore the original comment.

@madphysicist I thought I fixed that already by changing the coordinates to

xy = (0.3, 0.2)

can you please double check?

The more I touch this the more I think we should either inset or scrap the linking to the gallery examples 'cause the lack of mechanism to keep them in sync is causing major drift and like parts of this thing read like they refer to gallery examples that no longer exist. Also very out of scope of this PR.

I agree, we should not be relying on figures from examples in the tutorials. The tutorials should be self-contained. It's simple enough to make the plots in there (possibly enhanced by optional folding sphinx-gallery/sphinx-gallery#953 in the future for plots whose code is not so important). It's ok however, to link to an example in a "see also" style.

So I decided embedding the examples was in scope, I think mostly cause that was easier than checking for/reconciling discrepancies and there were sections of the tutorial that benefited from having the code written out rather than just linking out to a figure.

I intentionally avoided removing stuff from this tutorial, but what belongs in here is definitely arguable. There's now some repetition of gallery examples, but I think that's okay 'cause this allows for divergence down the line. Also a follow up issue/PR would be to clean up https://matplotlib.org/devdocs/gallery/userdemo/index.html and maybe to bring in the zoom code if code folding gets implement.

Another follow up option is maybe switch out some of the remaining source/target figures for the plot directive + show source link when #24215 goes in

Ping: I think it qualifies as better than it was if only cause the code examples now line up w/ the figures and the text.

Thank you! Totally agree that this needs more work, I just wanted it off my plate.