Skip to content

user's guide seriously denuded... #9349

Closed

Description

@jklymak

Bug report

The new user's guide has very little information in it:

http://matplotlib.org/2.0.2/users/index.html
http://matplotlib.org/users/index.html

Source...

This was introduced in #8545 @choldgraf I think..

Comentary.

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".

Activity

  1. anntzer commented on Oct 10, 2017

    @anntzer
    Contributor

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

  2. choldgraf commented on Oct 10, 2017

    @choldgraf
    Contributor
  3. jklymak commented on Oct 10, 2017

    @jklymak
    MemberAuthor

    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.

  4. choldgraf commented on Oct 10, 2017

    @choldgraf
    Contributor

    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

  5. jklymak commented on Oct 10, 2017

    @jklymak
    MemberAuthor

    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?

  6. choldgraf commented on Oct 10, 2017

    @choldgraf
    Contributor

    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.

  7. jklymak commented on Oct 10, 2017

    @jklymak
    MemberAuthor

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

  8. choldgraf commented on Oct 10, 2017

    @choldgraf
    Contributor

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

  9. jklymak commented on Oct 12, 2017

    @jklymak
    MemberAuthor

    Closed by #9381

  10. added this to the milestone on Oct 13, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions