You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
I think this is huge drop in content for the "User's Guide", and I'm not clear where we think a new user is to learn how to use Matplotlib after it is installed. I know that we should look in the tutorials, and I'm sure if I was new, I'd eventually think to look there, but the first thing I'd look for is the "User's Guide", and a simple example therein. This jumps straight from "Installing" to "Interactive Plots".
That's a good idea. Personally I think the new structure of the tutorials
is more intuitive than multiple levels of embedded documentation, though I
agree that we should make stronger links between the user guide and the
tutorials. I'm +1 to prs that drive users to the tutorials in the right
places
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.
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.
Activity
anntzer commentedon Oct 10, 2017
I would suggest linking back to the individual sections of the tutorial.
choldgraf commentedon Oct 10, 2017
jklymak commentedon Oct 10, 2017
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.
choldgraf commentedon Oct 10, 2017
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
jklymak commentedon Oct 10, 2017
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?
choldgraf commentedon Oct 10, 2017
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.
jklymak commentedon Oct 10, 2017
Yes, and its great! Wasn't trying to be critical of that effort, just that the top-level needs a bit of tweaking now.
choldgraf commentedon Oct 10, 2017
yeah, I totally agree with you :-) thanks for clarifying (and sorry if that came off as defensive)
jklymak commentedon Oct 12, 2017
Closed by #9381