[SciPy-Dev] updating optimize tutorial & doc questions
Mon Feb 6 11:52:24 CST 2012
On Mon, Feb 6, 2012 at 11:26 AM, <firstname.lastname@example.org> wrote:
> On Mon, Feb 6, 2012 at 12:03 PM, Denis Laxalde <email@example.com>
> > firstname.lastname@example.org wrote:
> >> > - The content of reference pages (e.g.
> >> > <http://docs.scipy.org/doc/scipy/reference/sparse.html>) appears to
> >> > be generated using automodule. There is also some bits in packages'
> >> > __init__.py file but this is not consistent with the latter. So
> >> > what's the documentation in __init__.py?
> >> It looks to me that it is now all in the module docstring, so the
> >> content of the main subpackage page should be directly the information
> >> in the __init__.py.
> >> What's the inconsistency?
> > It's kind of a mix of both contents. For example, in sparse/__init__.py,
> > there is:
> > eye - Sparse MxN matrix whose k-th diagonal is all ones
> > the online doc shows:
> > eye(m, n[, k, dtype, format]) eye(m, n) returns a sparse (m x
> n) matrix where the k-th diagonal
> > The latter description is the first line of `eye`'s docstring. This
> > is expected due to the `.. automodule:: scipy.sparse` which appears in
> > doc/source/sparse.rst. Some other parts of __init__.py (like examples)
> > are propagated "correctly".
> Ok, Warren just had a case where there was a rendering problem on one side.
> I haven't kept up with all the changes to the docs (since the info.py
> got dropped)
> The problem was always how to make it readable in the sphinx rendered
> docs and in the interpreter. The content of __init__.py shows up in
> help(sparse) or print sparse.__doc__ and has the extra information,
> that obviously gets overwritten by sphinx.
Expanding on Josef's comment:
The module-level docs violate the "don't repeat yourself" rule (but it is
much better now than it used to be, thanks to Ralf). Here's an example:
In scipy/integrate/__init__.py, you'll find:
Integration and ODEs (:mod:`scipy.integrate`)
.. currentmodule:: scipy.integrate
Integrating functions, given function object
quad -- General purpose integration.
dblquad -- General purpose double integration.
tplquad -- General purpose triple integration.
fixed_quad -- Integrate func(x) using Gaussian quadrature of order n.
quadrature -- Integrate with given tolerance using Gaussian quadrature.
romberg -- Integrate func using Romberg integration.
The documentation generated by Sphinx looks like this:
The autosummary directive tells Sphinx to get the descriptions
from the actual docstrings of the functions; the text after
the function names listed in __init__.py is ignored.
If you are in an interactive shell, however, and you enter
>>> from scipy import integrate
you will see the text exactly as it appears in __init__.py,
so we don't want to remove the (redundant) short descriptions
in that file. This mean you must copy the first line from the
function's docstring into __init__.py when you create a new
function or modify a function's docstring.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the SciPy-Dev