Re: [Numpy-discussion] Default value in documentation
On Tue, 2 Oct 2007, Charles R Harris apparently wrote: We're avoiding consolidated fields because they behave badly. ... The main problem with the consolidated fields is that they are all put together as item lists in a definition list and moved to the end of the docstring when it is rendered. There is also little control through the .css style sheet, they are all bulleted, and some of the types are missing. Is Ed Loper aware of this complaint? If so, has he indicated an interest (or lack) in addressing this complaint? Consolidated fields are great: it is a shame to do without them. Cheers, Alan Isaac ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
[Numpy-discussion] Default value in documentation
All,
I'm starting to update the documentation of maskedarray to the latest
standard.
How should I represent the default value of an optional parameter ?
I was thinking something like
def function(a, value=None)
Does something
*Parameters*:
a : {ndarray}
Input array.
value : {float} *[None]*
Some value. If None, a default based on the dtype of a is used.
Suggestions/ideas are welcome.
Thanks a lot in advance
P.
___
Numpy-discussion mailing list
Numpy-discussion@scipy.org
http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Default value in documentation
On 10/2/07, Robert Kern [EMAIL PROTECTED] wrote:
Pierre GM wrote:
All,
I'm starting to update the documentation of maskedarray to the latest
standard.
How should I represent the default value of an optional parameter ?
I was thinking something like
def function(a, value=None)
Does something
*Parameters*:
a : {ndarray}
Input array.
value : {float} *[None]*
Some value. If None, a default based on the dtype of a is used.
I prefer this:
value : {float}, optional
Some value. If not provided, a default based on the dtype of a is
used.
So label it optional and describe the default in prose in the parameter
description if necessary. While this is less descriptive for meaningful
defaults
(axis=-1), the case you show above is precisely suited to it. None is not
really
the default value, it's really just being used as a marker for argument
not
provided. And for the meaningful defaults, the function signature is more
than
adequate to provide the necessary information.
I've been putting the default value first among the options. Thus
axis : {-1, integer}, optional
Chuck
___
Numpy-discussion mailing list
Numpy-discussion@scipy.org
http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Default value in documentation
On Tue, 2 Oct 2007, Pierre GM apparently wrote: is there any kind of standard to describe the attributes of a class, a la :IVariables: in epydoc ? I thought it was ... :IVariables: i.e., I thought the standard was reST as handled by epydoc. URL:http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines URL:http://epydoc.sourceforge.net/api/epydoc.markup.restructuredtext-module.html#CONSOLIDATED_DEFLIST_FIELDS Cheers, Alan Isaac ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Default value in documentation
On 10/2/07, Alan G Isaac [EMAIL PROTECTED] wrote: On Tue, 2 Oct 2007, Pierre GM apparently wrote: is there any kind of standard to describe the attributes of a class, a la :IVariables: in epydoc ? I thought it was ... :IVariables: i.e., I thought the standard was reST as handled by epydoc. URL:http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines URL: http://epydoc.sourceforge.net/api/epydoc.markup.restructuredtext-module.html#CONSOLIDATED_DEFLIST_FIELDS We're avoiding consolidated fields because they behave badly. Chuck ___ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
