[SciPy-Dev] Cross-link scipy docs and source code?

[josef.pktd at gmail.com]

On Sun, Mar 11, 2012 at 7:51 AM, Christoph Deil
<deil.christoph at googlemail.com> wrote:
> Hi,
>
> would it be possible to cross-link the scipy docs and source code?
>
> I would find that very useful and I could imagine that this might in the
> long run lead to more scipy contributors (see recent mailing list thread
> that there are too few of those).
> More users will start to browse the code and understand how things are
> implemented and eventually feel competent enough to add the features they
> need in scipy instead of writing their own modules / wrappers based on
> scipy.
>
> Here's an example that shows how scipy docs currently look (no link to
> source code):
> http://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html
>
> statsmodels is an example of a  package that has cross-linked their auto
> docs and source code:
> http://statsmodels.sourceforge.net/generated/scikits.statsmodels.robust.robust_linear_model.RLM.html

IIRC, we added the source in statsmodels by accident, however I don't
find any discussion anymore.
It's a bit similar to the (old style) DOXYGEN generated documentation.
I don't think sphinx would handle parts of scipy that are not in
python.

I like having quick access to the source to see what a function
actually does. For scipy, I rely most of the time on the object
inspector in Spyder that is able to pull up the docstring and the
source, or sometimes on numpy.source

The only thing I would worry a bit with adding the source is the size
of the htmlhelp, but I don't think it will get too large or sluggish.

Josef

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