[SciPy-Dev] updating optimize tutorial & doc questions

[Warren Weckesser]

On Mon, Feb 6, 2012 at 11:26 AM, <josef.pktd at gmail.com> wrote:

> On Mon, Feb 6, 2012 at 12:03 PM, Denis Laxalde <denis.laxalde at mcgill.ca>
> wrote:
> > josef.pktd at gmail.com 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
============================================

.. autosummary::
   :toctree: generated/

   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.


etc.

The documentation generated by Sphinx looks like this:

   http://docs.scipy.org/doc/scipy/reference/integrate.html

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

Warren
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20120206/b1857a82/attachment.html>