[SciPy-user] Docstring standards for NumPy and SciPy

Janet Swisher swisher at enthought.com
Wed Jan 10 11:07:43 CST 2007


Darren Dale <dd55 at cornell.edu> wrote:

>
>> Lists:
>>
>>   * item1
>>     - subitem
>>       + subsubitem
>>   * item2
>>   * item3
>>
>> or
>>
>>   1. item1
>>      a. subitem
>>         i.  subsubitem1
>>         ii. subsubitem2
>>   2. item2
>>   3. item3
>>
>> for lists.
>>     
> [...]
>   
>> Tables:
>>
>> Tables should be constructed as either:
>>
>>          +------------------------+------------+----------+
>>
>>          | Header row, column 1   | Header 2   | Header 3 |
>>
>>          +========================+============+==========+
>>
>>          | body row 1, column 1   | column 2   | column 3 |
>>
>>          +------------------------+------------+----------+
>>
>>          | body row 2             | Cells may span        |
>>
>>          +------------------------+-----------------------+
>>
>> or
>>
>>          || Header row, column 1 || Header 2    || Header 3  ||
>>
>>          -------------------------------------------------------
>>
>>          || body row, column 1   || column 2    || column 3  ||
>>          || body row 2           |||| Cells may span columns ||
>>     
>
>
> >From a users perspective, thank you all for working on this.
>   
Agreed! Thanks to Travis for pushing the ball forward on this.
> If the Scipy/Numpy community is establishing a standard, now would be the time 
> to pick one format or the other for lists and tables. 

For tables, I agree that picking one format would be desirable. I 
personally prefer the second of the two examples, as it's simpler. The 
first type is tedious to construct and maintain, unless you use the 
emacs package that supports it; if "everybody" is using emacs, then the 
first type might be preferable.

For lists, however, I see a need for both bulleted and numbered list 
formats. There are times when you *want* to imply a sequence among the 
items, and there are other times when a sequence would be misleading. 
This is why HTML has both <OL> and <UL> lists.

-- 
Janet Swisher --- Senior Technical Writer
Enthought, Inc. http://www.enthought.com



More information about the SciPy-user mailing list