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.
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
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.
Mike
Cheers!
Ben Root
------------------------------------------------------------------------------
This SF.net email is sponsored by Windows:
Build for Windows Store.
http://p.sf.net/sfu/windows-dev2dev
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
------------------------------------------------------------------------------
This SF.net email is sponsored by Windows:
Build for Windows Store.
http://p.sf.net/sfu/windows-dev2dev
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
