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 <fabio.zan...@tuebingen.mpg.de>
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
> > <fabio.zan...@tuebingen.mpg.de <mailto:fabio.zan...@tuebingen.mpg.de>>
> > 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
> > Matplotlib-devel@lists.sourceforge.net
> > <mailto:Matplotlib-devel@lists.sourceforge.net>
> > 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
> Matplotlib-devel@lists.sourceforge.net
> 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
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
