[SciPy-Dev] Status of scipy.* docstrings

[Pauli Virtanen]

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.

Autosummary directives work correctly in submodule docstrings. For 
instance, this page:

  http://docs.scipy.org/doc/numpy/reference/routines.fft.html

comes solely from ``numpy/fft/info.py``:

  http://docs.scipy.org/doc/numpy/_sources/reference/routines.fft.txt
  http://docs.scipy.org/numpy/source/numpy/dist/lib64/python2.4/site-packages/numpy/fft/info.py

You can also write something like

.. autosummary::
   :toctree:

   some_function       Short blurb describing what it does 

and the "Short blurb ..." will be ignored in the HTML output, but it is 
useful for the people looking at the text via help().

-- 
Pauli Virtanen