Hi, 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. After each routine is properly documented there, We can have various index, category, and cross references. Oh boy :-) -Dieter
On Fri, Mar 21, 2008 at 3:55 AM, <vel.accel@gmail.com> wrote:
Hi,
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.
Knock yourself out. -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
Hi Dieter On Fri, Mar 21, 2008 at 9:55 AM, <vel.accel@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
4. Update the docstring, using the format suggested in
http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines
I realize this is a bit of a johnny-come-lately comment, but I was surprised to see that the list of sections does not seem to include the single most common reason I usually try to access a doc string ... the function signature. IMO, this item would ideally be the last item in a docstring so that one could quickly figure out which parameter belongs in which position, which are keywords, and what the defaults are without scrolling up multiple pages or having to mentally assemble this from a vertical list of parameters and optional parameters. Was this omission deliberate or an oversight? And more importantly, what do people think of adding it to the guidelines? Gary
pe, 2008-03-21 kello 07:53 -0400, Gary Strangman kirjoitti:
4. Update the docstring, using the format suggested in
http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines
I realize this is a bit of a johnny-come-lately comment, but I was surprised to see that the list of sections does not seem to include the single most common reason I usually try to access a doc string ... the function signature.
The function signature is automatically determined and shown for Python functions, both by help() and IPython ? or most tools that do generate docs from docstrings, adding it also to the docstring is extraneous. For functions implemented in C in extension modules, help() cannot find the signature automatically. However, the CodingStyleGuidelines does say that in this case including the function signature to the documentation is mandatory. -- Pauli Virtanen
http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines
I realize this is a bit of a johnny-come-lately comment, but I was surprised to see that the list of sections does not seem to include the single most common reason I usually try to access a doc string ... the function signature.
The function signature is automatically determined and shown for Python functions, both by help() and IPython ? or most tools that do generate docs from docstrings, adding it also to the docstring is extraneous.
For functions implemented in C in extension modules, help() cannot find the signature automatically. However, the CodingStyleGuidelines does say that in this case including the function signature to the documentation is mandatory.
Fair enough. I guess I'm just old-school ... standard python shell and not-infrequently directly-accessing the __doc__ attribute, which does not provide a function signature. Time for an ol' dog to learn new habits ... G
Hi Gary On Fri, Mar 21, 2008 at 12:53 PM, Gary Strangman <strang@nmr.mgh.harvard.edu> wrote:
4. Update the docstring, using the format suggested in
http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines
I realize this is a bit of a johnny-come-lately comment, but I was surprised to see that the list of sections does not seem to include the single most common reason I usually try to access a doc string ... the function signature. IMO, this item would ideally be the last item in a docstring so that one could quickly figure out which parameter belongs in which position, which are keywords, and what the defaults are without scrolling up multiple pages or having to mentally assemble this from a vertical list of parameters and optional parameters.
Was this omission deliberate or an oversight? And more importantly, what do people think of adding it to the guidelines?
No, this is not an oversight but a way to avoid duplicating the same information. In IPython, use the "?" to view the docstring, and the first thing you'll see is the function signature. For C functions we do include the signature, since it isn't shown. Regards Stéfan
read relow... On Fri, Mar 21, 2008 at 11:21 AM, Stéfan van der Walt <stefan@sun.ac.za> wrote:
Hi Dieter
On Fri, Mar 21, 2008 at 9:55 AM, <vel.accel@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
On Fri, Mar 21, 2008 at 8:54 AM, Sebastian Haase <haase@msg.ucsf.edu> wrote:
read relow...
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
Thats just a for placement. We can create all sorts of direct indexes, categories and cross-references, etc... -dieter _______________________________________________
Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
On 21/03/2008, Sebastian Haase <haase@msg.ucsf.edu> wrote:
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.
I don't have a solution, but I would like to complain about numpy's flat namespace. Perhaps we're stuck with it now, but it's very difficult to find the right function. In scipy, I can find the right numerical integration by importsing scipy.integrate and using tab completion, But in numpy, everything is loaded into the base namespace, so tab completion gets me an overwhelming 502 possibilities. That's why there's a "numpy functions by category" but no "scipy functions by category" - scipy functions are already by category. Is it perhaps possible to make all numpy functions accessible in submodules (in addition to in numpy, for backwards compatibility) and then promote accessing them that way? Are they already? If so how do I find out what the submodules are? Thanks, Anne
On Fri, Mar 21, 2008 at 2:47 PM, Anne Archibald <peridot.faceted@gmail.com> wrote:
On 21/03/2008, Sebastian Haase <haase@msg.ucsf.edu> wrote:
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.
I don't have a solution, but I would like to complain about numpy's flat namespace. Perhaps we're stuck with it now, but it's very difficult to find the right function. In scipy, I can find the right numerical integration by importsing scipy.integrate and using tab completion, But in numpy, everything is loaded into the base namespace, so tab completion gets me an overwhelming 502 possibilities. That's why there's a "numpy functions by category" but no "scipy functions by category" - scipy functions are already by category.
Is it perhaps possible to make all numpy functions accessible in submodules (in addition to in numpy, for backwards compatibility) and then promote accessing them that way? Are they already? If so how do I find out what the submodules are?
We should definately discuss and consider this proposal for 1.1. Do you have a suggested organisation in mind? Regards Stéfan
On 21/03/2008, Stéfan van der Walt <stefan@sun.ac.za> wrote:
On Fri, Mar 21, 2008 at 2:47 PM, Anne Archibald <peridot.faceted@gmail.com> wrote:
Is it perhaps possible to make all numpy functions accessible in submodules (in addition to in numpy, for backwards compatibility) and then promote accessing them that way? Are they already? If so how do I find out what the submodules are?
We should definately discuss and consider this proposal for 1.1. Do you have a suggested organisation in mind?
Not exactly. What do people think of the way I organized the numpy functions by category page? Apart from the sore-thumb "other" category, it does seem like the kind of grouping we might hope for. Anne
On Fri, Mar 21, 2008 at 5:00 PM, Anne Archibald <peridot.faceted@gmail.com> wrote:
On 21/03/2008, Stéfan van der Walt <stefan@sun.ac.za> wrote:
On Fri, Mar 21, 2008 at 2:47 PM, Anne Archibald <peridot.faceted@gmail.com> wrote:
Is it perhaps possible to make all numpy functions accessible in submodules (in addition to in numpy, for backwards compatibility) and then promote accessing them that way? Are they already? If so how do I find out what the submodules are?
We should definately discuss and consider this proposal for 1.1. Do you have a suggested organisation in mind?
Not exactly. What do people think of the way I organized the numpy functions by category page? Apart from the sore-thumb "other" category, it does seem like the kind of grouping we might hope for.
I can see categories 1 through 4 being one submodule, and the rest as they are. Stéfan
On Fri, Mar 21, 2008 at 9:32 AM, Stéfan van der Walt <stefan@sun.ac.za> wrote:
Not exactly. What do people think of the way I organized the numpy functions by category page? Apart from the sore-thumb "other" category, it does seem like the kind of grouping we might hope for.
I can see categories 1 through 4 being one submodule, and the rest as they are.
+1 -- Jarrod Millman Computational Infrastructure for Research Labs 10 Giannini Hall, UC Berkeley phone: 510.643.4014 http://cirl.berkeley.edu/
On Fri, Mar 21, 2008 at 1:54 PM, Sebastian Haase <haase@msg.ucsf.edu> wrote:
read relow...
On Fri, Mar 21, 2008 at 11:21 AM, Stéfan van der Walt <stefan@sun.ac.za> wrote:
Hi Dieter
On Fri, Mar 21, 2008 at 9:55 AM, <vel.accel@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
participants (9)
-
Anne Archibald -
dieter h -
Gary Strangman -
Jarrod Millman -
Pauli Virtanen -
Robert Kern -
Sebastian Haase -
Stéfan van der Walt -
vel.accel＠gmail.com