[SciPy-user] [SciPy-dev] Docstring standards for NumPy and SciPy

[Alan G Isaac]

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.


> 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.

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?


> 4) doesn't seem to have special processing for standard section headers 
> (I may be wrong about this as I'm not an reST expert. 

I am not sure what you mean here.  Section headers can be 
styled as you wish, pretty much.  What kind of "processing" 
is desired here?


> 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?
Really **bold**, *italics*, and ``fixed-width`` are
just as good.  (Note that you could even use single back 
ticks for fixed width by hijacking the default role,
but it seems better to save that for math?) Remember
that each time you steal a character you need some way
to escape it to get it back when needed: reST minimizes this.


> I like the {{{ code }}} for code blocks that Moin Moin uses, but that's 
> not a big deal to me.  I can live with the :: that restructured-Text uses. 

I think the reST convention is much cleaner.

fwiw,
Alan Isaac