On 01/09/2013 12:20 PM, Nelle Varoquaux wrote:
> Hi all,
> A while back, Mike drafted a MEP to modernize the documentation:
> 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,
> - 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
> - 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.
> 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:
> Matplotlib-devel mailing list