Usage

Install nbsphinx with pip (not available yet!) or copy the file nbsphinx.py to the directory where you want to set up Sphinx (this is typically the directory where you have your notebook files).

In the same directory, run this command (assuming you have Sphinx installed already):

sphinx-quickstart

Answer the questions that appear on the screen. In case of doubt, just press the <Return> key to take the default values.

After that, there will be a few brand-new files in the current directory. You’ll have to make a few changes to the file conf.py. Have a look at the conf.py of nbsphinx for the details.

Once your conf.py is in place, edit the file index.rst and add the file names of your notebooks (without the .ipynb extension) to the toctree directive.

To create the HTML pages, use this command:

sphinx-build <source-dir> <build-dir>

If you have many notebooks, you can do a parallel build by using the -j option:

sphinx-build <source-dir> <build-dir> -j<number-of-processes>

For example, if your source files are in the current directory and you have 4 CPU cores, you can run this:

sphinx-build . _build -j4

Afterwards, you can find the main HTML file in _build/index.html.

To create LaTeX output, use:

sphinx-build <source-dir> <build-dir> -b latex

Subsequent builds will be faster, because only those source files which have changed will be re-built. To force re-building all source files, use the -E option.

HTML Themes

The nbsphinx extension does not provide its own theme, you can use any of the available themes or create a custom one, if you feel like it.

Here are a few examples how the nbsphinx input and output cells look like in different themes:

http://nbsphinx.readthedocs.org/en/readthedocs-theme/

http://nbsphinx.readthedocs.org/en/alabaster-theme/

http://nbsphinx.readthedocs.org/en/bootstrap-theme/

http://nbsphinx.readthedocs.org/en/cloud-theme/

http://nbsphinx.readthedocs.org/en/py3doc-enhanced-theme/