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

[Ralf Gommers]

On Sun, Mar 11, 2012 at 2:05 PM, <josef.pktd at gmail.com> wrote:

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

Instead of doubling the size of the built docs, why not add a link to the
source file on Github?

Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20120311/bdf99556/attachment.html>