Re: [matplotlib-devel] Documentation Proposal

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

On Mon, Jun 17, 2013 at 10:05 AM, Michael Droettboom <md...@st...>wrote:

>  It might be a good idea to add some of these recommendations to MEP10,
> which serves somewhat as a guide to those that are going through and
> updating the docstrings.
>
>
Will do.  I will try to put something together prior to SciPy 2013 so that
they can be discussed.


>
> On 06/15/2013 02:34 PM, Benjamin Root wrote:
>
>     As I continue to put together my tutorial for SciPy 2013, I have come
> to realize several things that are lacking with our documentation.  First
> of all, while the pyplot summary table:
> http://matplotlib.org/1.3.0/api/pyplot_summary.html is a great addition,
> it is still a huge mis-mash of different kinds of functions.  Some
> functions are for plotting, others are for figure and axes prep, and others
> are for decorating the plot.  I am just about done with my reorganized list
> and will post it for others to comment and possibly include for that page.
>
>
> Sounds good.
>
>
>  Second, if there is one thing that Matlab gets right, it is its
> documentation.  Let's compare the doc page for the hist() function:
>
> http://matplotlib.org/1.3.0/api/pyplot_api.html#matplotlib.pyplot.hist
> http://www.mathworks.com/help/matlab/ref/hist.html
>  (for those with NoScript, you will want javascript turned on for the
> mathworks page)
>
>  First off, I think there is some sort of error in the docstring because
> the sphinx rendering is a bit messed up.  Second, in the matlab doc page,
> there is a dead simple, complete, concise example for each call signature,
> and an image of the plot to go with it.
>
>  I think this is key.  I am finding some functions that have examples that
> demonstrate more than just the plotting function, i.e., hexbin(), or are
> missng examples altogether, i.e., matshow() and pie().
>
>  So, my proposal is this.  For every plotting function, there should be a
> minimalist, complete example available to demonstrate it. Further, that
> example and its result should be easily viewable from the function's
> documentation.  For organization's sake, I would suggest having a
> consistent naming scheme for this kind of example.  Lastly, such an example
> should be required as part of any pull request to add new plotting
> functions.
>
> Also sounds good.  Let's add that to the pull request checklist here:
>
> http://matplotlib.org/devel/coding_guide.html
>
>
I'll put together a PR with a proposed naming scheme and a first pass at
creating a bunch of these examples.  I was thinking that it might be nice
to put together a "gallery" of some sort that showcases the plotting
functions that are available using these simple examples, and clicking on
the image would take you to the documentation for that function.

>
>  As a side note related to "easily viewable example code", one thing I
> don't like about the examples in the doc strings is that they don't provide
> me a link to one of these pages:
> http://matplotlib.org/1.3.0/examples/pie_and_polar_charts/pie_demo_features.html.
> Those pages are nice because I can see the code and the image it produces
> at the same time.  Instead, those API doc pages just gives me a link to
> download the source code, or to view the image.  Is it at all possible to
> have the example sphinx directive include a link to those example pages
> when rendering the API documentation?
>
>
> It is possible -- it's not really how it works now.  The example pages are
> generated from python source files in the examples/ tree, whereas the
> docstring examples are inserted inline into the docstring (or sometimes
> referencing external files).  But with a little tweaking of the plot
> directive extension, it should be possible.
>
>
We can certainly flesh out the idea some more during SciPy2013.

In the meantime, a "bug" I have noticed.  In the list of markers:
http://matplotlib.org/1.3.0/api/markers_api.html, we have things like
"TICKLEFT", "CARETUP" and such. These seem to be some sort of placeholder
for the numerical values and is quite confusing.  I suspect this has been
this way for a while now.

Cheers!
Ben Root