[SciPy-Dev] Status of scipy.* docstrings

Scott Sinclair scott.sinclair.za@gmail....
Thu Aug 5 06:03:30 CDT 2010


On 5 August 2010 11:01, Pauli Virtanen <pav@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


More information about the SciPy-Dev mailing list