[Numpy-discussion] Improving Docs on Wiki

[Stéfan van der Walt]

On Fri, Mar 21, 2008 at 1:54 PM, Sebastian Haase <haase at msg.ucsf.edu> wrote:
> read relow...
>
> On Fri, Mar 21, 2008 at 11:21 AM, Stéfan van der Walt <stefan at sun.ac.za> wrote:
>  > 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
>  > [...]
>  >
>
>  Comment:  I have read the module- or directory-name "core" many times
>  on this list, however: Who really knows where a given functions
>  belongs ?  Isn't that mostly only the numpy svn commiters ?
>  In other words, using only the python side of numpy,  someone (like
>  myself) would NOT know that sort is inside "core" !

The idea is to merge the docstrings back into the source, so that you
can simply do

numpy.sort?

in IPython and see the latest updated version.  For that purpose, you
don't need to know where the sort method is located.  We do, however,
need to know in order to have some sane organisation of the
documentation on the wiki.

>From a user's perspective, other alternatives include doing a wiki
search, or following my earlier advice and using "?" in IPython to see
where the function is located.

Regards
Stéfan