matplotlib-devel Mailing List for matplotlib

OK made a pull request with the first changes (1): #4187.
Cheers,
F
On 03/03/2015 10:56 PM, Benjamin Root wrote:
> The website is generated by sphinx from the docstrings and other
> components in the doc/ directory of the matplotlib project. The file for
> the home page can be found:
> https://github.com/matplotlib/matplotlib/blob/master/doc/_templates/index.html
> 
> By the way, the file for the "Documenting mpl" page is here:
> https://github.com/matplotlib/matplotlib/blob/master/doc/devel/documenting_mpl.rst
> 
> And, like I said, even if you don't get around to actually making any
> changes, at the very least, I would file these issues as "bugs" to our
> issue tracker.
> 
> Cheers!
> Ben Root
> 
> On Tue, Mar 3, 2015 at 4:40 PM, Fabio Zanini
> <fab...@tu... <mailto:fab...@tu...>>
> wrote:
> 
> Hi Ben,
> 
> Well, excellent or not I just hope it helps a bit. I can put some effort
> if people agree that this is useful, though I am quite busy at the
> moment. Who's currently actually managing the website?
> 
> Thx!
> F
> 
> On 03/03/2015 21:33, Benjamin Root wrote:
> > This is excellent insight! It should be fairly trivial to fix points 1
> > and 2, and I agree that it would make the page much more inviting to
> > newcomers.
> >
> > Point 3 would take some time. I had never noticed that before.
> > Personally, I think the issue about documentation isn't that it is
> > boring (I actually find them interesting), it is that by the time one
> > gets into a project to actually start contributing, you become immune to
> > the deficiencies in the documentation. Insights like these from
> > newcomers are like gold to those of us who have been around for a while.
> >
> > Feel free to either create some pull requests to address some of these
> > points, or at least file some bug reports so that we don't completely
> > forget this. I may even be able to pick up some of it once my book
> > finalizes for printing in the next week or two.
> >
> > Cheers!
> > Ben Root
> >
> >
> > On Tue, Mar 3, 2015 at 2:35 PM, Fabio Zanini
> > <fab...@tu...
> <mailto:fab...@tu...>
> <mailto:fab...@tu...
> <mailto:fab...@tu...>>>
> > wrote:
> >
> > Dear Thomas,
> >
> > Finally got some time to reply about the docs. My main point
> is not
> > about the API docs themselves, although they would need some
> tuning à la
> > MEP10. Rather, as Sebastian's doubts about pyplot/axes shows, I am
> > considering an issue with the non-API part of the docs, i.e.
> the user
> > guide, tutorial, and website.
> >
> > MY OLD PROBLEM WITH THE DOCS
> >
> > Now I am more experienced with mpl so I just read the API docs and
> > figure my way through, but at the beginning I remember that
> whenever I
> > was wondering about something I would quickly end up in either
> of two
> > places:
> >
> > - the pyplot API page: http://matplotlib.org/api/pyplot_api.html
> >
> > This is a giant blob of a page and takes several seconds just
> to load.
> > It's lacking any kind of menu or navigation help, just the
> whole docs
> > straight out - alphabetical order - and bam!
> >
> > - stackoverflow
> >
> > Here people give practical suggestions, but they are
> inconsistent (some
> > use pyplot, some axes methods, sometimes even more low-level
> code). I
> > mean, it does work, but it's messy and not very instructive
> for newbies
> > (imagine learning say chemistry from stackoverflow, not fun uh?)
> >
> >
> > HOW TO MAKE IT BETTER
> >
> > This one's harder, but I'd have a couple of ideas:
> >
> > 1. better home page
> >
> > The beginner's guide should be accessible from the home page
> in ONE
> > click, possibly highlighted in a frame or so. It currently takes 3
> > clicks on small text hyperlinks to get to some introduction,
> the pyplot
> > tutorial:
> >
> > HOME -> DOCS -> BEGINNER'S GUIDE -> PYPLOT TUTORIAL
> >
> > (and it's not even the first link on those pages). Some quick
> visual
> > snippet (possibly interactive e.g. an IPython notebook?) and
> maybe a
> > video tutorial like golang would be helpful:
> >
> > http://golang.org/
> >
> > 2. More navigation support on the pyplot API page
> >
> > I realize API docs need to be somewhat stiff in order to make
> sure you
> > find what you're looking for (alphabetical order and so), but some
> > side-menu, quick example, or highlighting of the most common items
> > (plot, scatter) would be useful. I've read the acorr API docs
> 100 times
> > by now, and never, ever used it ;-P
> >
> > 3. clear presentation of the protagonist (Axes)
> >
> > As far as I understand, the main object for the user is the
> Axes class.
> > For instance, does the code below look familiar to anyone?
> >
> > ax.plot(x, y)
> > ax.scatter(x, y)
> > ax.set_xscale('log')
> > ax.set_xlabel('My x axis')
> > ax.set_xticks(...)
> > ax.legend()
> > ax.set_title('My title')
> > ax.grid(True)
> >
> > Nonetheless, this kind of Axes-based coding is not even
> mentioned in the
> > beginner's guide. You may now think it's in the advanced guide
> but, no!
> > - the advanced guide only talks about "Artists" in general,
> not the Axes
> > in particular: "Artist tutorial", "Customizing your objects", etc.
> > I am not criticizing past mainteners for this organization,
> but I would
> > support a more Axes-centric tutorial in the beginner's guide.
> >
> > As of the time issue, it's the usual problem, nobody wants to
> do the
> > docs because they are boring. It's true, it's a bit boring.
> But that
> > also depends a bit: writing API docs can be boring, but writing a
> > tutorial for newbies can be fun!
> >
> > Cheers,
> > Fabio
> >
> >
> > 
> ------------------------------------------------------------------------------
> > Dive into the World of Parallel Programming The Go Parallel
> Website,
> > sponsored
> > by Intel and developed in partnership with Slashdot Media, is your
> > hub for all
> > things parallel software development, from weekly thought
> leadership
> > blogs to
> > news, videos, case studies, tutorials and more. Take a look
> and join the
> > conversation now. http://goparallel.sourceforge.net/
> > _______________________________________________
> > Matplotlib-devel mailing list
> > Mat...@li...
> <mailto:Mat...@li...>
> > <mailto:Mat...@li...
> <mailto:Mat...@li...>>
> > https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
> >
> >
> 
> 
> ------------------------------------------------------------------------------
> Dive into the World of Parallel Programming The Go Parallel Website,
> sponsored
> by Intel and developed in partnership with Slashdot Media, is your
> hub for all
> things parallel software development, from weekly thought leadership
> blogs to
> news, videos, case studies, tutorials and more. Take a look and join the
> conversation now. http://goparallel.sourceforge.net/
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> <mailto:Mat...@li...>
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
> 
>