[Numpy-discussion] Improving Docs on Wiki
Fri Mar 21 07:54:59 CDT 2008
On Fri, Mar 21, 2008 at 11:21 AM, Stéfan van der Walt <email@example.com> wrote:
> Hi Dieter
> On Fri, Mar 21, 2008 at 9:55 AM, <firstname.lastname@example.org> 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.
> If you need to know where a function belongs, use IPython's "?" to inspect it:
> In : np.core.sort?
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:
<function sort at 0x01BACB30>
<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.
> 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:
> 3. Copy the current docstring into the page (inside the rst section).
> 4. Update the docstring, using the format suggested in
> >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 : %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.
More information about the Numpy-discussion