IPython notebooks + Sphinx!!¶
Do the usual sphinx-quickstart
In the source folder create an IPython notebook, say hello.ipynb
Use nbconvert to export the notebook as a rst file.
$ipython nbconvert hello.ipynb --to rst
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:
.. 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.
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!