On Mon, Jun 17, 2013 at 10:05 AM, Michael Droettboom <md...@stsci.edu>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
------------------------------------------------------------------------------
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
