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