Hi Dieter On Fri, Mar 21, 2008 at 9:55 AM, <[EMAIL PROTECTED]> 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 _______________________________________________ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion