matplotlib-devel Mailing List for matplotlib

On Mon, Jun 17, 2013 at 9:50 AM, Michael Droettboom <md...@st...> wrote:
> We're a little behind schedule for 1.3.0 -- held up by the
> distribute/setuptools upgrade debacle. I'd like to put out a 1.3.0rc3
> late tonight or tomorrow, and hopefully get a final release out early
> next week in advance of Scipy if all goes well. Any objections?
>
I'm too far behind on my email to be apprised of the state of distribute vs
setuptools. I trust your judgement :)
>
> Mike
>
>
>
>
> ------------------------------------------------------------------------------
> 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
>
-- 
Damon McDougall
http://www.damon-is-a-geek.com
Institute for Computational Engineering Sciences
201 E. 24th St.
Stop C0200
The University of Texas at Austin
Austin, TX 78712-1229

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

We're a little behind schedule for 1.3.0 -- held up by the 
distribute/setuptools upgrade debacle. I'd like to put out a 1.3.0rc3 
late tonight or tomorrow, and hopefully get a final release out early 
next week in advance of Scipy if all goes well. Any objections?
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.
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