Documentation Proposal

Benjamin_Root1 · June 15, 2013, 6:34pm

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

Michael_Droettboom · June 17, 2013, 2:05pm

Sounds good.
Also sounds good. Let’s add that to the pull request checklist
here:
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

···

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.

                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://matplotlib.org/1.3.0/api/pyplot_api.html#matplotlib.pyplot.hist)

                [http://www.mathworks.com/help/matlab/ref/hist.html](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.

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?

Cheers!

Ben Root


------------------------------------------------------------------------------
This SF.net email is sponsored by Windows:
Build for Windows Store.

_______________________________________________
Matplotlib-devel mailing list

http://p.sf.net/sfu/windows-dev2dev Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

Benjamin_Root1 · June 17, 2013, 6:10pm

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.

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:
Plotting commands summary — Matplotlib 1.3.0 documentation 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:

pyplot — Matplotlib 1.3.0 documentation
Histogram plot (not recommended; use histogram) - MATLAB hist
(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:
pie_and_polar_charts example code: pie_demo_features.py — Matplotlib 1.3.0 documentation.
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:
Markers — Matplotlib 1.3.0 documentation, 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

···

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

On 06/15/2013 02:34 PM, Benjamin Root wrote:

Michael_Droettboom · June 18, 2013, 1:42am

Yes -- these are numeric enumerations defined in matplotlib.markers. That should be made clearer, or we should add string aliases for these things.

Mike

···

On 06/17/2013 02:10 PM, Benjamin Root wrote:

In the meantime, a "bug" I have noticed. In the list of markers: Markers — Matplotlib 1.3.0 documentation, 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.