[SciPy-Dev] Status of scipy.* docstrings

[Pauli Virtanen]

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.

It might be possible to autogenerate the info.py's, but frankly, I think 
setting that up is not a very useful use of time, just to avoid a few RST 
directives. We can think about it later, but for now the priority should 
be to get some useful information both to the HTML docs and to the 
command-line help, and putting everything to info.py seems the way to go 
for me.

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

The only exception is probably extensive examples, or extensive 
background information, which should probably be retained in the *.rst 
part, and maybe be split into several pages.

-- 
Pauli Virtanen