matplotlib-devel Mailing List for matplotlib

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...>
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...>>
> > 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...>
> > 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...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
>
>

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...>>
> 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...>
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
> 
> 

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...>
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...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
>
>

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