[SciPy-dev] are masked array statistical function hidden intentionally?
Wed Nov 19 09:08:14 CST 2008
Wed, 19 Nov 2008 08:55:19 -0500, Pierre GM wrote:
> I tend to edit the docstrings as I edit the code, and most functions/
> methods do have a proper docstring that follows the numpy standard.
> There's definitely a lack of examples and see alsos, though...
> I'm quite surprised to see that so many functions are not picked up
> during the doc build.
This is actually my fault -- I left sorting out the functions under numpy
submodules last when I added most other parts of numpy, and I haven't
still finished numpy.ma. Also numpy.emath, numpy.rec, numpy.numarray,
numpy.oldnumeric, numpy.ctypeslib, numpy.matlib would need work (but are
less important than MA).
> Pauli, could you point me towards the part of the autosummary/autodoc
> that lists the functions in a module ? Should I edit the docstring of
> the module to organize the output (using ..autofunction / ..automethod
> directives ? Is it legit to put sphinx directives/shortcuts in the doc,
> or are we still trying to ensure compatibility with an extra package?
The docs pick only those docstrings listed in an auto*:: directive in one
of the *.rst files.
Sphinx stuff will work in the docstrings, but also `numpy.foo` should
IIRC generate reference links (this comes from the numpy Sphinx
extension). I don't remember if Sphinx markup was discussed when the
docstring format was agreed on, but I remember people being worried about
making the docstrings more difficult to read on the terminal. If the
markup doesn't compromise this, at least I don't see problems with using
I think a useful way forward could be:
1. Editing numpy-docs/source/routines.ma.rst and adding any missing
utility functions inside the autosummary:: directives.
Mentioning a function/etc in an autosummary:: directive somewhere
in the documentation will instruct Sphinx to generate a separate page
for the function docstring, and link the function under that page in
the table of contents. (Though at present this doesn't work for
directives in module docstrings, only for those in .rst files.)
Including the documentation using the other auto*:: directives is OK,
but personally I find this a bit distracting. Numpy's docstrings tend
to become very long and detailed, so that a page with more than one on
it is difficult to read.
2. Editing numpy-docs/source/arrays.classes.rst and adding any missing
reference information (using autosummary::, or autoattribute:: etc.)
about the masked array objects there, possibly in the same way as in
arrays.ndarray.rst for the base ndarray.
Alternatively, split the MA documentation to a separate page, for
example arrays.ma.rst. I'm not sure what is the best organization
here or if it makes sense to split the MA docs in two places.
Except for the fact that autosummary:: directive doesn't fully function
inside module docstrings (this can probably be fixed), I believe the main
documentation can well be included in the module docstring. Then, one
would need to put only a single automodule:: directive in arrays.ma.rst
to dump the text there.
More information about the Scipy-dev