[Numpy-discussion] Improving Docs on Wiki

[Sebastian Haase]

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" !

Also: since >>> import numpy as N; N.sort  refers already to that same sort:
>>> N.core.sort
<function sort at 0x01BACB30>
>>> N.sort
<function sort at 0x01BACB30>

I would prefer not to require "core" sub-sub-page.
Instead, every name <X> that is accessible as N.<X> should be
documented without extra sub-page.

My 2 cents.
Thanks,
Sebastian



> 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