[SciPy-Dev] Status of scipy.* docstrings

[Scott Sinclair]

On 5 August 2010 11:01, Pauli Virtanen <pav at iki.fi> wrote:
> Thu, 05 Aug 2010 01:17:16 -0700, David Goldsmith wrote:
>> OK, so, should I stop adding autosummaries to module docstrings and
>> revert the ones I did?
>
> I think the Sphinx markup involved is not heavy, and having to maintain
> two nearly identical documents is not something we really want to do.
>
> I'd at least be OK with moving everything from the *.rst files to
> info.py. In general, I'd like to structure `info.py` in a similar way as
> it's in `numpy.fft`:
>
> - module name title etc. on top
>
> - function/class listing first
>
> - followed by background information (if any) needed to understand
>  what the module is intended to do
>
> - the corresponding .rst file contains only the line
>
>  .. automodule:: scipy.interpolate

This sounds like a good plan.

Just a note that all the edits made at
http://docs.scipy.org/scipy/docs/scipy.<sub-package> result in patches
from the doc-editor that target scipy/<sub-package>/__init__.py in the
source tree. If the patch is applied as is, the work from the
doc-editor won't appear in the terminal because the
<sub-package>.__doc__ is overwritten with the content of
scipy/<sub-package>/info.py on import of the sub-package. I expect
that Sphinx will also end up with the docstring from info.py for the
same reason, but don't have time to check right now.

Cheers,
Scott