[SciPy-dev] module docstrings

josef.pktd@gmai... josef.pktd@gmai...
Sat Oct 31 15:28:34 CDT 2009

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:
>> On Sun, Oct 25, 2009 at 5:58 AM, Ralf Gommers
> <ralf.gommers <at> googlemail.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.
> 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.
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev

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.)

I just rely on dir(modulename) to get the actual listing,
or better in some cases modulename.__all__  for only the public functions

matlab allows you to generate the contents.m file automatically or
semi-automatically, which makes it easier to maintain.


More information about the Scipy-dev mailing list