[SciPy-dev] are masked array statistical function hidden intentionally?

[Pauli Virtanen]

Hi Pierre,

Wed, 19 Nov 2008 08:55:19 -0500, Pierre GM wrote:
[clip]
> 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 
it.

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.

	Pauli