[SciPy-dev] module docstrings

Ralf Gommers ralf.gommers@googlemail....
Sun Oct 25 06:58:48 CDT 2009

Hi all,

The doc standard does not say anything about module docstrings, and before
starting to clean those up it would be nice to agree on a format.

Right now there are modules that:
- do not have any docstring (matrixlib, fromnumeric, ..)
- have license/author info in the docstring (scipy.interpolate.fitpack, ..)
- list their routines (linalg, core, lib, ..)
  * some of these have a routines rst doc: routines.linalg.rst exists,
routines.lib.rst does not.
- have a single summary line (distutils, ..)
- have some basic explanation (ma, scimath, ..)

What do you all think about the following? :

1. every module needs a docstring with at least a summary line.

2. follow the doc standard where relevant, so typically:
    - summary line
    - extended summary paragraph(s)
    - see also, if needed
    - notes, if needed
    - references, if needed

3. no routine listing in the docstring, each module gets a corresponding
routines.module.rst file

4. license and author info can be in the source file, but not in the
docstring. (same principle for author info in reST docs by the way).

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20091025/b834bd1c/attachment.html 

More information about the Scipy-dev mailing list