Re: [matplotlib-devel] Documentation Proposal

[Michael D. <md...@st...>]

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