Welcome to sphinx_ipynb’s documentation!¶

Contents:

Hello Sphinx!¶

IPython notebooks are great! Sphinx is cool as well. Let us add the two to have better docs. Let us do a bit of IPython jugglery. This page shows a demo of using some of IPython functionality and embedding it in sphinx docs.

import numpy as np
import pandas as pd
import seaborn as sns
import matplotlib.pyplot as plt
%matplotlib inline

Creating a dummy Pandas dataframe¶

df = pd.DataFrame(np.random.randn(50,2))

How does the dataframe display render?¶

df.head()

	0	1
0	2.658950	-1.113648
1	-0.638310	-0.109605
2	0.565121	1.423637
3	-0.612912	1.177100
4	1.267664	-1.739509

5 rows × 2 columns

What about plots?¶

df.plot();

How about maths?¶

\[x = \frac{y}{y+1}\]

Here is the IPython notebook corresponding to this page and here is the github repo corresponding to this minimal example! Many people are already using this scheme. I just documented it for my benefit (and possibly someone else also may find it useful).

– Nipun Batra

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!