ipython/nbconvert — pull request #35 by jakevdp (2012-09-23 05:46:02+00:00)
Title: WIP: Sphinx Notebook Extension

Description
----------------
This is a quick-and-dirty sphinx extension to include notebooks in sphinx documents. It's based on the raw html directive, so will only work with html.

Usage
---------
in your sphinx directory, add to `conf.py`:

sys.path.insert(0, '/path/to/nbcovert/')
extensions = ['notebook_sphinxext']

Then in your sphinx document, use:

.. notebook:: path/to/notebook.ipynb

Then type `make html`, and you should see your notebook embedded in your sphinx document.

Problems
--------------
There are a few problems with this implementation... some will be fairly easy to fix, while some need some ipython/sphinx expertise that I don't have.

- since this is based on the `raw` directive, it will only work in html, not latex or other outputs. Fixing this will involve diving deeper into sphinx, and also writing a notebook to LaTeX converter
- currently the entire html file is included. This means there are extra `` and `

` tags. To do this right, the css portion needs to be added to the header on the sphinx page build - I'm not sure how to do this.
- it would be nice to add a flag which optionally adds a link to the notebook file for download.
- I'm sure there are more issues... someone with more sphinx experience could probably help out!