IPython notebooks + Sphinx!!

Step I

Do the usual sphinx-quickstart

Step II

In the source folder create an IPython notebook, say hello.ipynb

Step III

Use nbconvert to export the notebook as a rst file.

$ipython nbconvert hello.ipynb --to rst

Step IV

Add the newly generated rst to your toctree. In my case, for demo purposes, I added it to index.rst. So, the contents of my index.rst look as follows:

!cat index.rst

.. sphinx_ipynb documentation master file, created by
   sphinx-quickstart on Thu May  8 11:31:26 2014.
   You can adapt this file completely to your liking, but it should at least
   contain the root toctree directive.

Welcome to sphinx_ipynb's documentation!
========================================

Contents:

.. toctree::
   :maxdepth: 2

   hello
   howto



Indices and tables
==================

* Index
* Module Index
* Search Page

NB: here howto corresponds to the rendering of the current page.

Step V

The usual sphinx stuff for building html. From the main sphinx folder:

$ make html

If everything goes right, you should have your html in build/html

Step VI (Optional)

Let us install sphinx-bootstrap theme and use it for prettier rendering (non-trivial to use with readthedocs).

$ pip install sphinx_bootstrap_theme

Also, the conf.py needs to be edited as per instructions on this page.

Step VII (Hosting)

One may host on github pages or on readthe docs. I have used both. I host this repo on readthedocs (and thus commented out sphinx_bootstrap_theme related stuff!

That is it folks!