matplotlib-devel

[matplotlib-devel] API Documentation usability

[Sebastian W. <swe...@gm...>]

I'm a newcomer to the MPL code, and getting an overview is not easy.
Especially the API part of the documentation [1] has a lot of room for
improvement. The functionality of the MPL sources seems to be
scattered quite loosely among the sources and their structure is
directly mirrored in the doc. Some observations:

1. Many functions like quiver() or bar() are in multiple places
(pyplot and axes)
2. Some entries (like axes) are enormous, making them very hard to use
to get an overview
3. The API start page is just a lose list of classes, without
indication what's inside

Ideally I feel like the code itself should be organized in smaller
chunks, but that's probably unrealistic. A quick improvement for 2.
could be to add a "table of contents" at the top of every class
documentation. For axes, that could work like [2] and look like [3].
Thoughts? I wanted to test the waters before making pull requests.

Another way could be to organize the documentation not by classes, but
by functionality. The Numpy docs [4] seem much more usable in that
regard. That'll be less automatic of course but could help with
observation 3.

I've also found the Mep10 [5] on the Wiki with many good ideas, but
not sure if that lead somewhere.

Sebastian


[1] http://matplotlib.org/api/index.html
[2] https://github.com/s9w/matplotlib/commit/053179c9491637609775e21855f21e977580a0a1
[3] http://i.imgur.com/d1uTjfS.png
[4] http://docs.scipy.org/doc/numpy/reference/
[5] https://github.com/matplotlib/matplotlib/wiki/Mep10

Re: [matplotlib-devel] API Documentation usability

[Fabio Z. <fab...@tu...>]

Dear Sebastian,

I agree with your impression. I made a pull request for some axis
functionality (logit scales) and the PR got lost. I am convinced that:

1. working on things like axes, ticker, scales, locators would be a lot
easier with a little refactoring of the code

2. with a more modular codebase, my PR would be accepted by now, instead
of living in limbo waiting to be forgotten.

So I am in general in favour of your proposal.

See also: https://github.com/matplotlib/matplotlib/pull/3753

Cheers,
Fabio

PS: if Thomas or anybody else is still willing to accept my PR itself,
I'd be in favour too. But please do not make me rebase another 3 times
before that ;-)

On 02/16/2015 11:42 AM, Sebastian Werhausen wrote:
> I'm a newcomer to the MPL code, and getting an overview is not easy.
> Especially the API part of the documentation [1] has a lot of room for
> improvement. The functionality of the MPL sources seems to be
> scattered quite loosely among the sources and their structure is
> directly mirrored in the doc. Some observations:
> 
> 1. Many functions like quiver() or bar() are in multiple places
> (pyplot and axes)
> 2. Some entries (like axes) are enormous, making them very hard to use
> to get an overview
> 3. The API start page is just a lose list of classes, without
> indication what's inside
> 
> Ideally I feel like the code itself should be organized in smaller
> chunks, but that's probably unrealistic. A quick improvement for 2.
> could be to add a "table of contents" at the top of every class
> documentation. For axes, that could work like [2] and look like [3].
> Thoughts? I wanted to test the waters before making pull requests.
> 
> Another way could be to organize the documentation not by classes, but
> by functionality. The Numpy docs [4] seem much more usable in that
> regard. That'll be less automatic of course but could help with
> observation 3.
> 
> I've also found the Mep10 [5] on the Wiki with many good ideas, but
> not sure if that lead somewhere.
> 
> Sebastian
> 
> 
> [1] http://matplotlib.org/api/index.html
> [2] https://github.com/s9w/matplotlib/commit/053179c9491637609775e21855f21e977580a0a1
> [3] http://i.imgur.com/d1uTjfS.png
> [4] http://docs.scipy.org/doc/numpy/reference/
> [5] https://github.com/matplotlib/matplotlib/wiki/Mep10
> 
> ------------------------------------------------------------------------------
> Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server
> from Actuate! Instantly Supercharge Your Business Reports and Dashboards
> with Interactivity, Sharing, Native Excel Exports, App Integration & more
> Get technology previously reserved for billion-dollar corporations, FREE
> http://pubads.g.doubleclick.net/gampad/clk?id=190641631&iu=/4140/ostg.clktrk
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
> 

Re: [matplotlib-devel] API Documentation usability

[Thomas C. <tca...@gm...>]

At risk of sounding defensive, all of the core developers are working mpl
on a mostly volunteer basis and only have so much bandwidth. This leads to
both thing falling through the cracks (we have close to 100 open PRs, that
is _way_ too many) and major re-factors (which every one agrees should be
done) not being done.

I fully agree the docs are less than ideal.  Some of what you suggest is
already on the radar (giving each plotting function it's own page) and a
complete overhaul of the webpage is (very slowly) in the works.
http://matplotlib.org/api/pyplot_summary.html covers some of the use-case
of the table of contents.

The reason that plotting methods appear in both `Axes` and in `pyplot` is
due to the layered design of mpl.  The actual plotting logic is implemented
as methods on the Axes object and the pyplot layer provides a MATLAB-like
state machine to make plotting convenient.  The fact that you have the same
functions in both places is a feature, not a bug ;).  We don't use
decorators for `pyplot.py` because that code pre-dates fully functional
decorators.

This part of the design, the plotting logic being _methods_ on the `Axes`
object, is why the `Axes` class is so large and I do not think can be
broken up in any sensible way (at the code level) short of abandoning it
all together and moving to modules of functions with signatures like
`fun(ax, data, style)`.  This has been discussed, but it is a HUGE change
to the architecture of the library and we are (rightly) moving slowly on
it.  MPL is a widely used mature library which means one of the most
important things we have to do is not break existing user code.

Providing human curation to the docs (a-la numpy) would be great, the main
problem is time.  The core-devs (who seem to enjoy very drudgery) are
already over whelmed, 'update the docs' is not really an exciting thing
that new contributors will jump on, and fixing the docs does require a good
deal of familiarity with the library (so you know where the docs are
wrong/misleading/missing!).

@Fabio  That bit of the already seems pretty modular, but I am not super
familiar with it.  What would you change?

If anyone wants to help with MEP10 that would be great!

Tom

On Mon Feb 16 2015 at 7:02:13 AM Fabio Zanini <fab...@tu...>
wrote:

> Dear Sebastian,
>
> I agree with your impression. I made a pull request for some axis
> functionality (logit scales) and the PR got lost. I am convinced that:
>
> 1. working on things like axes, ticker, scales, locators would be a lot
> easier with a little refactoring of the code
>
> 2. with a more modular codebase, my PR would be accepted by now, instead
> of living in limbo waiting to be forgotten.
>
> So I am in general in favour of your proposal.
>
> See also: https://github.com/matplotlib/matplotlib/pull/3753
>
> Cheers,
> Fabio
>
> PS: if Thomas or anybody else is still willing to accept my PR itself,
> I'd be in favour too. But please do not make me rebase another 3 times
> before that ;-)
>
> On 02/16/2015 11:42 AM, Sebastian Werhausen wrote:
> > I'm a newcomer to the MPL code, and getting an overview is not easy.
> > Especially the API part of the documentation [1] has a lot of room for
> > improvement. The functionality of the MPL sources seems to be
> > scattered quite loosely among the sources and their structure is
> > directly mirrored in the doc. Some observations:
> >
> > 1. Many functions like quiver() or bar() are in multiple places
> > (pyplot and axes)
> > 2. Some entries (like axes) are enormous, making them very hard to use
> > to get an overview
> > 3. The API start page is just a lose list of classes, without
> > indication what's inside
> >
> > Ideally I feel like the code itself should be organized in smaller
> > chunks, but that's probably unrealistic. A quick improvement for 2.
> > could be to add a "table of contents" at the top of every class
> > documentation. For axes, that could work like [2] and look like [3].
> > Thoughts? I wanted to test the waters before making pull requests.
> >
> > Another way could be to organize the documentation not by classes, but
> > by functionality. The Numpy docs [4] seem much more usable in that
> > regard. That'll be less automatic of course but could help with
> > observation 3.
> >
> > I've also found the Mep10 [5] on the Wiki with many good ideas, but
> > not sure if that lead somewhere.
> >
> > Sebastian
> >
> >
> > [1] http://matplotlib.org/api/index.html
> > [2] https://github.com/s9w/matplotlib/commit/
> 053179c9491637609775e21855f21e977580a0a1
> > [3] http://i.imgur.com/d1uTjfS.png
> > [4] http://docs.scipy.org/doc/numpy/reference/
> > [5] https://github.com/matplotlib/matplotlib/wiki/Mep10
> >
> > ------------------------------------------------------------
> ------------------
> > Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server
> > from Actuate! Instantly Supercharge Your Business Reports and Dashboards
> > with Interactivity, Sharing, Native Excel Exports, App Integration & more
> > Get technology previously reserved for billion-dollar corporations, FREE
> > http://pubads.g.doubleclick.net/gampad/clk?id=190641631&
> iu=/4140/ostg.clktrk
> > _______________________________________________
> > Matplotlib-devel mailing list
> > Mat...@li...
> > https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
> >
>
> ------------------------------------------------------------
> ------------------
> Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server
> from Actuate! Instantly Supercharge Your Business Reports and Dashboards
> with Interactivity, Sharing, Native Excel Exports, App Integration & more
> Get technology previously reserved for billion-dollar corporations, FREE
> http://pubads.g.doubleclick.net/gampad/clk?id=190641631&
> iu=/4140/ostg.clktrk_______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
>

Re: [matplotlib-devel] API Documentation usability

[Fabio Z. <fab...@tu...>]

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

Re: [matplotlib-devel] API Documentation usability

[Benjamin R. <ben...@ou...>]

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

Re: [matplotlib-devel] API Documentation usability

[Fabio Z. <fab...@tu...>]

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

Re: [matplotlib-devel] API Documentation usability

[Benjamin R. <ben...@ou...>]

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

Re: [matplotlib-devel] API Documentation usability

[Fabio Z. <fab...@tu...>]

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