[SciPy-Dev] Status of scipy.* docstrings
Thu Aug 5 06:03:30 CDT 2010
On 5 August 2010 11:01, Pauli Virtanen <firstname.lastname@example.org> 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.
More information about the SciPy-Dev