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

[Pauli Virtanen]

Wed, 19 Nov 2008 10:35:22 -0500, Pierre GM wrote:
[clip]
> I agree that there should be at least one specific
> page for numpy.ma functions/methods, organized by topics. Where should I
> create it (them) ?

I suggest making a new RST file "arrays.ma.rst" under numpy-docs/source.

[clip]
> Mmh, my question was more about links to other functions/methods inside
> the docstring, using for example :func:, :meth:, :attr: fields...

I don't know. Do :meth: and :attr: work in Sphinx with the bare method 
names without adding prefixes, if you haven't nested your method:: and 
attribute:: in the class:: directive. If yes, then they'll probably just 
work.

>> 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.
> 
> Can you remind me where I can find numpy-docs ? It's not on the numpy
> SVN, right ? What's the address of the repository ? Do I have write
> access to it ?

Ah yes, it's currently at http://svn.scipy.org/svn/numpy/numpy-docs/trunk/

It's technically a part of Numpy's SVN repo, so that if you can commit to 
Numpy, you can commit to the docs. I believe that we'll move the docs 
under the doc/ dir in the main numpy trunk in the near future, so that 
they're easier to find and can be tagged etc. at the same time as the 
code.

>>   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.
> 
> Agreed. I guess I'll find templates on the numpy-docs site, right ?

Yes, I believe taking a look at what's there now may help. (They're also 
linked to from docs.scipy.org in the sidebar.)

>>   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.
> 
> Well, there are 2 different aspects: the actual implementation
> (functions docstring), and some kind of tutorial. This latter may find
> its place in numpy/docs, actually...

Well, I think the implementation docs should also reside in numpy/doc, at 
least the functions should be manually grouped to smaller categories that 
make sense, so that it is easier to find the correct one if you don't 
exactly know what you are looking for.

At present, I'd suggest putting tutorial material to a separate file in 
the source/user/ directory so that it goes to the "User Guide". Btw, I'm 
at present not sure if it makes sense to put the tutorial stuff so far 
from the reference stuff, so we may need to reorganize this later on.

	Pauli