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
[email protected]
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
------------------------------------------------------------------------------
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
[email protected]
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
