Search code examples
pythonjupyter-notebookpython-sphinx

embed ipython notebook in sphinx document

I am writing the API document for my own project. And I found that this cool documentation (yt project) uses ipython notebook directly to give example. When I looked into their documentation repo on bitbucket, one relevant rst seemed quite simple as: 

.. notebook:: An_example_notebook.ipynb

But, of course, it didn't work for me. I am not sure if the "notebook" is an intrinsic block type or not. Maybe the 'notebook' block requires an external package. Actually, I got zero result when I searched for "notebook" in the sphinx documentation.

If I can use my notebooks directly (without converting) to give examples, that will make life much easier. But I can't figure out how I can achieve that.

Solution

  • nbsphinx is a Sphinx extension that provides a source parser for *.ipynb files.

    To Install nbsphinx:

    pip install nbsphinx --user

    Edit your conf.py and add 'nbsphinx' to extensions.

    Edit your index.rst and add the names of your *.ipynb files to the toctree.

    Follow This Link after the above thing you do

    Run Sphinx!