[SciPy-user] Docstring standards for NumPy and SciPy

Darren Dale dd55 at cornell.edu
Wed Jan 10 09:30:47 CST 2007


On Wednesday 10 January 2007 09:43, Travis Oliphant wrote:
> There was a lively discussion on the SciPy List before Christmas
> regarding establishing a standard for documentation strings for NumPy /
> SciPy.
[...]
> I'd like to get something done within the next few days (like placing
> the standard on a wiki and/or placing a HOWTO_DOCUMENT file in the
> distribution of NumPy).
[...]
> I've looked through a large number of documentation strings that I've
> written over the years and believe that the following format suffices.
> I would like all documentation to follow this format.
[...]
> 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.

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. It would be nice if the 
wiki/HOWTO_DOCUMENT included a template as well as a specific example that 
illustrates each element of a properly formatted docstring in more detail, to 
help documentation writers to produce something that feels consistent. Could 
these documents also include instructions for where and how users without 
commit privileges should submit documentation patches or requests?

Darren


More information about the SciPy-user mailing list