[IPython-dev] Using sphinx to evaluate notebook cells?

Nathan Goldbaum nathan12343 at gmail.com
Tue Oct 29 06:16:32 EDT 2013

Quick update on this.  I managed to create the notebook extension I was asking about in my initial message to the list. I did end up using runipy, as Matthias suggested.

Much of hard work for the extension was originally done by Anthony Scopatz, who wrote a similar notebook sphinx plugin for pyne (http://pynesim.org/) based on evaluated notebooks.

Using Anthony's extension, I generalized it to evaluate and embed the notebook in our docs. As a proof-of-concept, I transferred the yt bootcamp, which we had displayed in the past using static nbviewer links, to use the new notebook directive.

The result is here: http://ngoldbaum.net/docs_build/bootcamp/index.html

If you're interested in the details of how this works, the code for the plugin is here. One issue is that I had to monkeypatch the CSS I got back from nbconvert to avoid mangling our docs theme.

I've also created a similar notebook-cell extension that transforms inline .rst code snippets into evaluated notebook cells in the docs build.

For now these extensions are part of the yt documentation, but if there's interest I'll happily package up the extensions and do a standalone release for them.


On October 23, 2013 at 1:13:08 AM, Matthias Bussonnier (bussonniermatthias at gmail.com) wrote:


I'm not aware of such a plugin. Definitively interested as we want our doc as notebook in IPython too.

Have a look at runipy (Google is your friend, and is on pypi iirc). It runs notebook headless and generate static HTML from that. Having a nbconvert preprocessor that run notebook would also be great!

(Sorry no direct link, from my phone)


Envoyé de mon iPhone

Le 23 oct. 2013 à 02:41, Nathan Goldbaum nathan12343 at gmail.com a écrit :

Hi all,

Myself and some of the other yt devs are thinking about ways to improve cookbook section of our documentation by replacing the scripts we currently host with notebooks.

Since some of our cookbook recipes store plots, we'd like to track these notebooks in version control in an unevaluated state, mainly to avoid versioning images. We have a CI server that already builds our cookbook recipes for our dev docs, so something that integrates with sphinx seems to be the way to go. I think I could write a sphinx plugin that does the job, but it would need to use whatever machinery IPython uses when notebook cells get evaluated.

Does anyone know if such a plugin is available somewhere? If not, does anyone know where I should look in the IPython codebase for when I try to write it myself?

Thanks for your help,


IPython-dev mailing list IPython-dev at scipy.org http://mail.scipy.org/mailman/listinfo/ipython-dev

IPython-dev mailing list IPython-dev at scipy.org http://mail.scipy.org/mailman/listinfo/ipython-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/ipython-dev/attachments/20131029/0fd884af/attachment.html>

More information about the IPython-dev mailing list