[Numpy-discussion] Improving Docs on Wiki

[Stéfan van der Walt]

Hi Dieter

On Fri, Mar 21, 2008 at 9:55 AM,  <vel.accel at gmail.com> wrote:
>  I want to know if creating individual documentation for each numpy
>  routine on the scipy.org wiki would, for some administrative reason
>  (or other) be frowned upon. Here is an example of what I'd like to do
>  for all of numpy's routines. http://www.scipy.org/sort.

Thank you very much for contributing to NumPy.  Your timing is
perfect, today being our third doc-day -- I hope others join us as
well at #scipy on freenode.net, as we improve the documentation
coverage.  In a discussion with Fernando and Gael, we've come up with
some suggestions.

The wiki is a great place for users to add documentation, since it
doesn't require special permissions, but we shall run into naming
conflicts if we create top-level pages for all the numpy functions
(some also exist in scipy, for example).  I have created a
NumpyDocstrings category on the wiki, and suggest that we organise the
functions underneath it according to their numpy subpackage, e.g.

scipy.org/NumpyDocstrings/core/sort

If you need to know where a function belongs, use IPython's "?" to inspect it:

In [4]: np.core.sort?
[...]
File:
/Users/stefan/lib/python2.5/site-packages/numpy/core/fromnumeric.py
[...]

For these pages to be truly useful, we should re-absorb them into the
NumPy docstrings.  This would be difficult to do using Moin markup, so
let's use ReST throughout.  The suggested procedure is therefore:

1. Create NumpyDocstrings/subpackage/funcname
2. Start out the page with the following template:

{{{
#!rst

}}}
----
NumpyDocstrings

3. Copy the current docstring into the page (inside the rst section).
4. Update the docstring, using the format suggested in

   http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines

>From these pages, we can then automatically generate patches to the
NumPy source.

We also have a NumPy Examples List on the wiki.  Many of these should
be incorporated into the docstrings as examples.  Using IPython,
switch into doctest_mode:

In [3]: %doctest_mode
*** Pasting of code with ">>>" or "..." has been enabled.
Exception reporting mode: Plain
Doctest mode is: ON

>>>

Here you can generate examples for use in the "Examples" section,
while still having access to the enhanced capabilities of IPython.

These guidelines should provide us with a system which preserves but
enhances the current doctests, with the possibility of re-integrating
community contributions back into the source tree.

Thanks again for your help.

Regards
Stéfan