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).
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.
···
On Wed, Jan 9, 2013 at 6:20 PM, Nelle Varoquaux <nelle.varoquaux@...149...>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)
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 01/09/2013 12:43 PM, Todd wrote:
On Wed, Jan 9, 2013 at 6:20 PM, Nelle
Varoquaux <nelle.varoquaux@…149…>
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.
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.
This dovetails nicely with Tony Yu’s reorganization of the examples.
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
···
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, 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)
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
------------------------------------------------------------------------------
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:
_______________________________________________
Matplotlib-devel mailing list