[SciPy-Dev] Status of scipy.* docstrings

Scott Sinclair scott.sinclair.za@gmail....
Mon Aug 2 01:51:01 CDT 2010


>On 2 August 2010 00:34,  <josef.pktd@gmail.com> wrote:
>
> My impression was that module docstrings, in __init__.py and info.py
> are mainly for the commandline/interpreter, and I thought for most
> subpackages they are or were not included in the sphinx rendered docs.

This is correct, __init__.py and info.py are not included in the
Sphinx rendered docs. I think Pauli hand copied their contents into
the <sub-package>.rst files when he created those.

> In this case, autosummary would be noise in the interpreter and not
> picked up by sphinx, which uses the corresponding rst files.

The autosummary directives have only been added in the
<sub-package>.rst files, not the __init__.py and info.py files, so the
Sphinx markup won't appear in the interpreter. The <sub-package>.rst
files and corresponding __init__/info.py files currently have no link
and will need to be separately maintained.

It shouldn't be hard to strip out the Sphinx directives from the
<sub-package>.rst files and periodically copy the updated content into
the __init__.py and info.py, so it probably makes sense to work on the
<sub-package>.rst files for now.

Cheers,
Scott


More information about the SciPy-Dev mailing list