matplotlib-devel Mailing List for matplotlib

On 01/09/2013 12:20 PM, Nelle Varoquaux wrote:
> Hi all,
>
> A while back, Mike drafted a MEP to modernize the documentation:
>
> https://github.com/matplotlib/matplotlib/wiki/Mep10
>
> The main idea behind this MEP is to use the full potential of new 
> tools and conventions available for sphinx, to make the documentation 
> more readable, maintainable and consistent over the codebase. The main 
> proposed changes are the following:
>
> - follow the numpy docstring format, which is widely adopted among 
> scientific python projects (numpy, scipy, scikit-learn, scikit-image, 
> etc).
> - use the autodoc_docstring_signature of sphinx 1.1, which allow to 
> have the explicit function signature instead of the python one in the 
> generated documentation (args* and **kwargs are replaced by the 
> explicits arguments)
> - replace the duplication of the documentation (by concatenating 
> docstrings) by explicits references. This will shorten the docstrings.
> - use the autosummary extension of sphinx (sphinx aggregates small 
> classes on one page, while classes with many methods such as xes.axes 
> have one page dedicated to them)
My suggestion is actually that large classes (like Axes) would be broken 
up to multiple pages (one per method). Smaller classes can remain on 
the same page. Sphinx doesn't do any automatic determination here (as 
far as I know), but we can decide how to organize it on a class-by-class 
basis.
> - examples should link to relevant documentation
This dovetails nicely with Tony Yu's reorganization of the examples.
>
> The implementation is going to be long and tedious: Mike has separated 
> it 5 steps, that can be done independently from one another.
> If this MEP has been accepted, I can start implementing it (with step 1).
When I initially brought this MEP to the mailing list (as now), the only 
controversy was surrounding the function signatures. I think we can 
proceed with the plan to move function signatures to the top of the 
docstring for now (this is reasonably easy, since they're in the 
docstrings now, just not in a format that Sphinx can readily use). If a 
proposal is made that allows us to use **kwargs less in the first place, 
that can be done independently of the docstring changes. (Worst case, 
we end up removing the signatures from the docstrings later). But I 
haven't found a solution to the **kwargs problem that addresses the need 
to extend many disparate methods simultaneously in the future.
We can wait a little to see if there are further comments, but I think 
there's probably little major controversy over the rest of the MEP.
Mike
>
> Thanks,
> N
>
>
>
> ------------------------------------------------------------------------------
> Master Java SE, Java EE, Eclipse, Spring, Hibernate, JavaScript, jQuery
> and much more. Keep your Java skills current with LearnJavaNow -
> 200+ hours of step-by-step video tutorials by Java experts.
> SALE 49ドル.99 this month only -- learn more at:
> http://p.sf.net/sfu/learnmore_122612
>
>
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

On 01/09/2013 12:43 PM, Todd wrote:
> On Wed, Jan 9, 2013 at 6:20 PM, Nelle Varoquaux 
> <nel...@gm... <mailto:nel...@gm...>> wrote:
>
> - use the autodoc_docstring_signature of sphinx 1.1, which allow
> to have the explicit function signature instead of the python one
> in the generated documentation (args* and **kwargs are replaced by
> the explicits arguments)
>
>
> If you have to manually write out the function signature anyway, 
> might this be an opportunity to review whether the use of *args and 
> **kwargs is really necessary on a case-by-case basis? I would think 
> from a code clarity and maintenance standpoint minimizing the use of 
> *args and **kwargs would be beneficial.
This approach is very useful for adding new features across many 
methods. For example, the artist properties can be extended to support, 
for example, gradient fills, without updating all of the many plotting 
methods that support filled objects. I think this is an incredibly 
powerful feature to have, and now that Sphinx and IPython both support 
extracting the signature from the docstring when present, the downsides 
are rather minor.
Mike

On Wed, Jan 9, 2013 at 6:20 PM, Nelle Varoquaux
<nel...@gm...>wrote:
>
> - use the autodoc_docstring_signature of sphinx 1.1, which allow to have
> the explicit function signature instead of the python one in the generated
> documentation (args* and **kwargs are replaced by the explicits arguments)
>
>
If you have to manually write out the function signature anyway, might
this be an opportunity to review whether the use of *args and **kwargs is
really necessary on a case-by-case basis? I would think from a code
clarity and maintenance standpoint minimizing the use of *args and **kwargs
would be beneficial.

Hi all,
A while back, Mike drafted a MEP to modernize the documentation:
https://github.com/matplotlib/matplotlib/wiki/Mep10
The main idea behind this MEP is to use the full potential of new tools and
conventions available for sphinx, to make the documentation more readable,
maintainable and consistent over the codebase. The main proposed changes
are the following:
- follow the numpy docstring format, which is widely adopted among
scientific python projects (numpy, scipy, scikit-learn, scikit-image, etc).
- use the autodoc_docstring_signature of sphinx 1.1, which allow to have
the explicit function signature instead of the python one in the generated
documentation (args* and **kwargs are replaced by the explicits arguments)
- replace the duplication of the documentation (by concatenating docstrings)
by explicits references. This will shorten the docstrings.
- use the autosummary extension of sphinx (sphinx aggregates small classes
on one page, while classes with many methods such as Axes.axes have one
page dedicated to them)
- examples should link to relevant documentation
The implementation is going to be long and tedious: Mike has separated it 5
steps, that can be done independently from one another.
If this MEP has been accepted, I can start implementing it (with step 1).
Thanks,
N

>
>
> I can work on that and submit a PR.
>
I've submitted a PR (this is Work In Progress):
https://github.com/matplotlib/matplotlib/pull/1647
I think ``get_sample_data`` should be moved to a public, documented module,
as, unlike other methods from the cbook module, it is meant for public use.
>
> >
> > Cheers,
> > Mike
> >
> >
> >>
> >> Thanks,
> >> N
> >>
> >>> Mike
> >>>
> >>>
> >>> On 01/07/2013 10:24 AM, Nelle Varoquaux wrote:
> >>>>
> >>>> Hello everyone,
> >>>>
> >>>> I was recently looking at the cbook module, and I was wondering
> >>>> whether this module was public or not. I think there are several
> >>>> unused method in it, such as ``unmasked_index_ranges``. If this isn't
> >>>> public, it may be worth cleaning the module a bit and removing the
> >>>> unused method.
> >>>>
> >>>> Cheers,
> >>>> Nelle
> >>>>
> >>>>
> >>>>
> ------------------------------------------------------------------------------
> >>>> Master Visual Studio, SharePoint, SQL, ASP.NET, C# 2012, HTML5, CSS,
> >>>> MVC, Windows 8 Apps, JavaScript and much more. Keep your skills
> current
> >>>> with LearnDevNow - 3,200 step-by-step video tutorials by Microsoft
> >>>> MVPs and experts. SALE 99ドル.99 this month only -- learn more at:
> >>>> http://p.sf.net/sfu/learnmore_122412
> >>>> _______________________________________________
> >>>> Matplotlib-devel mailing list
> >>>> Mat...@li...
> >>>> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
> >>>
> >>>
> >>>
> >>>
> ------------------------------------------------------------------------------
> >>> Master Visual Studio, SharePoint, SQL, ASP.NET, C# 2012, HTML5, CSS,
> >>> MVC, Windows 8 Apps, JavaScript and much more. Keep your skills current
> >>> with LearnDevNow - 3,200 step-by-step video tutorials by Microsoft
> >>> MVPs and experts. SALE 99ドル.99 this month only -- learn more at:
> >>> http://p.sf.net/sfu/learnmore_122412
> >>> _______________________________________________
> >>> Matplotlib-devel mailing list
> >>> Mat...@li...
> >>> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
> >
> >
>