[SciPy-user] [SciPy-dev] Docstring standards for NumPy and SciPy
Travis Oliphant
oliphant at ee.byu.edu
Wed Jan 17 11:57:14 CST 2007
Alan G Isaac wrote:
>On Tue, 16 Jan 2007, Travis Oliphant apparently wrote:
>
>
>>In summary, my biggest issues with just straight
>>restructured Text are
>>1) back-ticks in parameter lists.
>>
>>
>
>I understood Ed to say:
>
>1) this can probably be dispensed with easily enough
>2) if dispensed with, we may lose cross refs from the
> parameters?
>
>I assume I misunderstood (2), since this is just a matter of
>how definition lists are parsed in consolidated fields, and
>definition lists definitely do not require the back tics.
>So I *think* Ed is saying both that this problem can be
>overcome and that he is willing to help with it.
>
>
Great. Getting rid of back-ticks in the parameters section would help
a great deal.
So does this mean
:Parameters:
a : array
this is something
b : int
this is a scalar input
could be how argument parameters are specified?
This would be fine.
I'd like an additional "field" name to describe little used parameters
so that functions with a large number of keyword argument can still be
well documented without cluttering the main parameters list. Is that
possible?
Where are these standard field names used?
>
>
>
>>2) the way math is included
>>
>>
>
>I understood Ed to say that for inline math we could just
>make LaTeX the default role, so that we write e.g.,
>`f(x)=x^2`. Back ticks look at least as good as dollar
>signs, IMO.
>
>
I don't have a problem with back-ticks used for math.
>The cost is that cross refs then must be explicitly marked.
>How important are these considered to be for the
>documentation? (How did you intend to mark them?)
>
>I did not get a sense of how easy it would be to make dollar
>signs special (so they could be used to indicate a math role).
>I guess it would not be hard, but I feel
>pretty confident that this would NOT be welcomed as some
>kind of patch to reST. (But I'm just a user.)
>
>
>
>
>>3) doesn't understand Moin Moin tables
>>
>>
>
>This seems just a matter of hacking reST, it seems to me.
>I hazard that the reST developers would welcome a patch to
>handle Moin Moin tables. In the meantime I ask, what
>features missing from reST tables would actually be used?
>
>
>
>
I don't care so much about this. I'm not wedded to Moin Moin's
definition of tables except it seemed pretty minimialistic and easy to use.
>
>
>
>>I also don't really like the way bold, italics, and
>>courier are handled. My favorite is now *bold* /italics/
>>and `fixed-width`.
>>
>>
>
>This seems to me not worth haggling over. Right?
>
>
I agree. I'm not that concerned about it.
I think if we can agree on a suitable description of the parameters list
and on what to do about including math (I don't think there will be a
lot of math in docstrings but there may need to be some, so we ought to
think about it) then we are there for using reST in docstrings.
I guess my major reaction to reST was the prevalent use of backticks in
parameter descriptions. I can see now that this is not a requirement of
reST but only a convention. I'd prefer a different convention for
NumPy/SciPy.
-Travis
More information about the SciPy-user
mailing list