[SciPy-Dev] Status of scipy.* docstrings

[josef.pktd at gmail.com]

On Thu, Aug 5, 2010 at 5:01 AM, Pauli Virtanen <pav at iki.fi> 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.
>
> 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.

One issue is the amount of math/latex, given the discussion we had on fftpack.
Do we restrict latex in the module docstring as in function or class
docstrings, or is it allowed to be used not only very sparingly?

Since info.py files can also be edited in the module editor, I also
think removing the duplication is a good idea.

A related question that is not urgent: Are we keeping the split of
information between tutorial and sub-package rst pages, or should some
background information be moved to the package rst files ?

Josef


>
> --
> Pauli Virtanen
>
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>