[SciPy-dev] module docstrings

Ralf Gommers ralf.gommers@googlemail....
Mon Nov 2 11:07:12 CST 2009

On Sat, Oct 31, 2009 at 9:28 PM, <josef.pktd@gmail.com> wrote:

> On Sat, Oct 31, 2009 at 4:02 PM, Tom K. <tpk@kraussfamily.org> wrote:
> > Ralf Gommers <ralf.gommers <at> googlemail.com> writes:
> >
> >>
> >>
> >> On Sat, Oct 31, 2009 at 2:21 AM, Charles R Harris
> > <charlesr.harris <at> gmail.com> wrote:
> >> I like routine listings....
> >>
> > MATLAB has a default behavior for documenting a directory on the path
> when
> > you don't have a Contents.m in that directory: it pulls the "H1" line
> (first
> > line of the M-file's help) from each M-file and lists those for you.
> > But the Contents.m usually was nicely formatted and grouped according
> > to function, with a list of each M-file with a 1-line summary.
> > FWIW.
> > I kind of like a listing too, but not all functions in all modules
> warrant
> > listing at the module level - there is an asymmetry problem.
> >

This is basically what the reST routines listings do already; one listing
per area of functionality, and pulling the first line of the docstrings. See
for example

Also remember that the contents.m for Matlab is necessary in many cases
because of the one-file-per-function limit, for a Python module in a single
file with __all__ at the top this is not nearly as important.

> I'm not sure the info files in scipy are kept up to date. Since we
> moved the documentation to the rst files, I haven't looked at info.py
> anymore, except for those packages that have an automodule directive
> and load the info script. (If I'm not mistaken about the import
> mechanism for the docs.)

You're not mistaken. I'll look into an easy way to keep the existing info
files updated.

> I just rely on dir(modulename) to get the actual listing,
> or better in some cases modulename.__all__  for only the public functions
> Yes, you have both of those options, plus most IDE's give you nice
overviews, or taglists in vim and (i assume) emacs.

I created a ticket with a patch to the docstandard,
http://projects.scipy.org/numpy/ticket/1280 (keeping routine listings as an
optional section), and will start working on module docs soon.

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

More information about the Scipy-dev mailing list