[SciPy-Dev] Status of scipy.* docstrings

[Scott Sinclair]

>On 2 August 2010 11:32,  <josef.pktd at gmail.com> wrote:
> On Mon, Aug 2, 2010 at 2:51 AM, Scott Sinclair
> <scott.sinclair.za at gmail.com> wrote:
>>>On 2 August 2010 00:34,  <josef.pktd at 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.
>
> my understanding:
>
> >From the source tab in http://docs.scipy.org/scipy/docs/scipy.fftpack/
> , it looks like this is destined for info.py which is pulled in by
> __init__.py.
> The rst docs are at http://docs.scipy.org/scipy/docs/scipy-docs/fftpack.rst/

Hmm. Good point. I was looking at the way the docs are built from the
source tree, not at what was edited in the doc-editor.

When the documentation is generated from the source tree, the Sphinx
master document doc/source/index.rst pulls in doc/source/fftpack.rst,
not __init.__.py. In the doc-editor doc/source/index.rst is at
http://docs.scipy.org/scipy/docs/scipy-docs/index.rst/.

The solution would be to use the recent edits at
http://docs.scipy.org/scipy/docs/scipy.<subpackage>/ to update what's
at http://docs.scipy.org/scipy/docs/scipy-docs/<subpackage>.rst/ then
remove the Sphinx directives from
http://docs.scipy.org/scipy/docs/scipy.<subpackage>/ or just revert
them to what's in trunk for now.

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..

Cheers,
Scott