[SciPy-Dev] Status of scipy.* docstrings

[Scott Sinclair]

On 2 August 2010 13:24, Pauli Virtanen <pav at iki.fi> wrote:
> Mon, 02 Aug 2010 12:34:24 +0200, Scott Sinclair wrote:
> [clip]
>> Maybe the http://docs.scipy.org/scipy/docs/scipy.<subpackage>/
>> docstrings should also be marked as unimportant to warn people that the
>> situation is a little tricky to unravel..
>
> A valid alternative is just to put all of the documentation to the
> info.py, and just put
>
>        .. automodule:: scipy.optimize
>
> to the optimize.rst.

This is the approach I prefer as well. I tried to suggest it the last
time we had this discussion
(http://mail.scipy.org/pipermail/scipy-dev/2010-June/015075.html).
Then there is only one place to keep the docs up to date, the downside
being that a bit of Sphinx markup will be seen in the terminal help
for sub-packages.

The question is whether there actually is a strong aversion to seeing
Sphinx markup in the terminal help at the top-level of the
sub-packages. If it doesn't bother too many people, then your
suggestion is the right way to go for all of the Scipy sub-packages.

Cheers,
Scott