[SciPy-Dev] updating optimize tutorial & doc questions

[josef.pktd at gmail.com]

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.

Josef

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