[SciPy-dev] module docstrings

[Ralf Gommers]

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

> On Sat, Oct 31, 2009 at 4:02 PM, Tom K. <tpk at 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
http://docs.scipy.org/numpy/docs/numpy-docs/reference/routines.indexing.rst/

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.

Cheers,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20091102/e92e69b7/attachment.html>