Cross-link scipy docs and source code?
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.... 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.robu... Christoph
On Sun, Mar 11, 2012 at 7:51 AM, Christoph Deil <deil.christoph@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....
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.robu...
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@scipy.org http://mail.scipy.org/mailman/listinfo/scipy-dev
On Sun, Mar 11, 2012 at 2:05 PM, <josef.pktd@gmail.com> wrote:
On Sun, Mar 11, 2012 at 7:51 AM, Christoph Deil <deil.christoph@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....
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.robu...
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
11.03.2012 14:25, Ralf Gommers kirjoitti: [clip]
Instead of doubling the size of the built docs, why not add a link to the source file on Github?
Yep. Scipy has ~ 5 MB of Python code, and adding HTML formatting on top of that would blow up the size by some factor. Sphinx doesn't seem to have a pre-built extension for this, but it seems pretty easy to just write one up and submit it to them. We can keep it in Numpy's sphinxext for the time being. Pauli
On 11 March 2012 13:42, Pauli Virtanen <pav@iki.fi> wrote:
Sphinx doesn't seem to have a pre-built extension for this
The Python language docs have some way of linking to the source, see e.g. http://docs.python.org/py3k/library/tempfile.html Thomas
On Sun, Mar 11, 2012 at 11:06 AM, Thomas Kluyver <thomas@kluyver.me.uk> wrote:
On 11 March 2012 13:42, Pauli Virtanen <pav@iki.fi> wrote:
Sphinx doesn't seem to have a pre-built extension for this
The Python language docs have some way of linking to the source, see e.g. http://docs.python.org/py3k/library/tempfile.html
Thomas
small detour on a related question: Does sphinx have a build in way to switch themes or css between building html and htmlhelp? Does anyone know? searching with google and on stackoverflow is unsuccessful. The answer maybe: ask at a relevant mainling list. (Sorry for the noise, in that case.) Josef
_______________________________________________ SciPy-Dev mailing list SciPy-Dev@scipy.org http://mail.scipy.org/mailman/listinfo/scipy-dev
11.03.2012 17:50, josef.pktd@gmail.com kirjoitti: [clip]
searching with google and on stackoverflow is unsuccessful. The answer maybe: ask at a relevant mainling list. (Sorry for the noise, in that case.)
You can probably use tags.has('html') or tags.has('htmlhelp') as conditionals in the config file. Pauli
On Sun, Mar 11, 2012 at 1:23 PM, Pauli Virtanen <pav@iki.fi> wrote:
11.03.2012 17:50, josef.pktd@gmail.com kirjoitti: [clip]
searching with google and on stackoverflow is unsuccessful. The answer maybe: ask at a relevant mainling list. (Sorry for the noise, in that case.)
You can probably use tags.has('html') or tags.has('htmlhelp') as conditionals in the config file.
Thanks tags didn't work because it is empty, {}, in conf.py but this told me where to start and look, sys.argv is available in conf.py if 'htmlhelp' in sys.argv: html_theme = 'statsmodels_htmlhelp' else: html_theme = 'statsmodels' (Although I didn't find a nice css, so I just use default if 'htmlhelp' in sys.argv ) Josef
Pauli
_______________________________________________ SciPy-Dev mailing list SciPy-Dev@scipy.org http://mail.scipy.org/mailman/listinfo/scipy-dev
On Sun, Mar 11, 2012 at 2:42 PM, Pauli Virtanen <pav@iki.fi> wrote:
11.03.2012 14:25, Ralf Gommers kirjoitti: [clip]
Instead of doubling the size of the built docs, why not add a link to the source file on Github?
Yep. Scipy has ~ 5 MB of Python code, and adding HTML formatting on top of that would blow up the size by some factor.
Sphinx doesn't seem to have a pre-built extension for this, but it seems pretty easy to just write one up and submit it to them. We can keep it in Numpy's sphinxext for the time being.
Apparently "pretty easy" means "I'll fix it right this minute". It's live already: http://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.... Thanks Pauli! Ralf
On Mar 13, 2012, at 7:26 PM, Ralf Gommers wrote:
On Sun, Mar 11, 2012 at 2:42 PM, Pauli Virtanen <pav@iki.fi> wrote: 11.03.2012 14:25, Ralf Gommers kirjoitti: [clip]
Instead of doubling the size of the built docs, why not add a link to the source file on Github?
Yep. Scipy has ~ 5 MB of Python code, and adding HTML formatting on top of that would blow up the size by some factor.
Sphinx doesn't seem to have a pre-built extension for this, but it seems pretty easy to just write one up and submit it to them. We can keep it in Numpy's sphinxext for the time being.
Apparently "pretty easy" means "I'll fix it right this minute". It's live already: http://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize....
Thanks Pauli!
Ralf
This is great! Thanks! Christoph
participants (5)
-
Christoph Deil -
josef.pktd＠gmail.com -
Pauli Virtanen -
Ralf Gommers -
Thomas Kluyver