[SciPy-dev] module docstrings

[Ralf Gommers]

On Sat, Oct 31, 2009 at 2:21 AM, Charles R Harris <charlesr.harris at gmail.com
> wrote:

>
>
> On Sun, Oct 25, 2009 at 5:58 AM, Ralf Gommers <ralf.gommers at googlemail.com
> > wrote:
>
>> 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
>>
>>
> I like routine listings. They may not add much to the processed
> documentation, but I find it helpful to have routines listed up top with
> some short notes when looking at the source. It is also an easy way to see
> what is in a module without having to browse through its directory listing.
>

There are actually only 3 modules (+2 by mistake) in all of NumPy that have
listings if I counted correctly. If you think those are useful maybe we can
make it an optional section (i.e. they should not be deleted, but most
modules don't need them)?

In NumPy, the ones with listings are:
- numerictypes
- fftpack
- arraysetops
- random (accidental copy of random.info)
- linalg (accidental copy of linalg.info)

In addition there are a few large modules with listings in separate info
files:
- core
- lib
- random
- linalg
- fft

In SciPy listings for modules (stats, interpolate, integrate, special, ...)
also reside in info files.

Cheers,
Ralf



>
> 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).
>>
>>
> Chuck
>
>
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20091031/d81ba81f/attachment.html>