I would suggest linking back to the individual sections of the tutorial.

Yeah, OK I can maybe make some PRs at some point, but I find the documentation infrastructure pretty hard to grok. I'm sure there is a proper way to link to the tutorials, but I don't know what that is. Further, it takes 10 minutes to build on my machine just to see if a small change that I've made has been formatted properly. Its unfortunate that the build is so slow when I've only changed one file.

FWIW, I think the new tutorial sections are fabulous, and I agree thats a good way to organize the docs. I just think we need to consider the role of the "User's Guide" in light of that organization.

the documentation is a beast to build, it's really unfortunate :-/

FWIW, everything in sphinx-gallery is build with a tag at the top that's based off of the file name. So we can use that tag to reference the tutorials. E.g., see the markdown associated with this section of the whats_new page: https://github.com/matplotlib/matplotlib/blob/master/doc/users/whats_new.rst#enhancements-to-polar-plot

if you open PRs I can spot check links etc...the docs will auto-build on circle, so we can always see the built documentation on there before merging if you can't get it to build on your machine

Awesome! Thaks a lot... My suggestion would be to put the TOC thats in tutorials/index in the user guide as well.

I still think the upper level organization bears some thought that I'm not qualified to make the decisions on. i.e. we produce a PDF of the User Guide, but again, its nearly empty. Why does "interactive plots" get orphaned in the Users Guide, but everything else got moved to tutorials?

I believe that @tacaswell is interested in putting together a more comprehensive plan for the documentation. The current state of the tutorials/user guide is largely a product of how much time and energy @NelleV and I had, as getting it switched to sphinx-gallery and reorganized was huge, multi-month-long effort.

Yes, and its great! Wasn't trying to be critical of that effort, just that the top-level needs a bit of tweaking now.

yeah, I totally agree with you :-) thanks for clarifying (and sorry if that came off as defensive)

Closed by #9381