nbsphinx#

nbsphinx is a Sphinx extension that provides a parser for *.ipynb files: Jupyter Notebook code cells are displayed in both HTML and LaTeX output. Notebooks with no output cells saved are automatically created during the Sphinx build process.

Installation#

$ pipenv install sphinx nbsphinx

Requirements#

Configuration#

Configure Sphinx#

  1. Creating a documentation with Sphinx:

    $ pipenv run python -m sphinx.cmd.quickstart

  2. The Sphinx configuration file conf.py is then located in the newly created directory. In this, nbsphinx is added as an extension and notebook checkpoints are excluded:

    extensions = [
    ...
    "nbsphinx",
]
...
exclude_patterns = [
    ...
    "**/.ipynb_checkpoints",
]

    You can find an example in the /conf.py file of the Jupyter tutorial.

You can make further configurations for nbsphinx.

Timeout

In the standard setting of nbsphinx, the timeout for a cell is set to 30 seconds. You can change this for your Sphinx project in the conf.py file with nbsphinx_timeout = 60.

Alternatively, you can also specify this for individual code cells in the metadata of the code cell:

{
 "cells": [
  {
   "cell_type": "markdown",
   "nbsphinx": {
     "timeout": 60
   }
  }
 ]
}

If the timeout is to be deactivated, -1 can be specified.

Custom formats

Libraries such as jupytext save notebooks in other formats, for example as R-Markdown with the suffix Rmd. So that these can also be executed by nbsphinx, further formats can be specified in the Sphinx configuration file conf.py with nbsphinx_custom_formats, for example

import jupytext


nbsphinx_custom_formats = {
    ".Rmd": lambda s: jupytext.reads(s, ".Rmd"),
}

Configure cells#

Don’t show cell
{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": "hidden"
   }
  }
 ]
}
nbsphinx-toctree

With this instruction Sphinx will create a table of contents within a notebook cell, for example

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx-toctree": {
      "maxdepth": 2
    },
   "source": [
    "The following title is rendered as ``toctree caption``.\n",
    "\n",
    "## Content\n",
    "\n",
    "[A notebook](a-notebook.ipynb)\n",
    "\n",
    "[An external HTML link](https://jupyter-tutorial.readthedocs.io/)\n"
   ]
   }
  }
 ]
}

Further options you will find in the Sphinx documentation.

Build#

  1. Now you can add your *.ipynb file in the table of contents of your index.rst file, see for example jupyter-tutorial/notebook/testing/index.rst

  2. Finally, you can generate the pages, for example HTML with $ pipenv run python -m sphinx SOURCE_DIR BUILD_DIR or $ pipenv run python -m sphinx SOURCE_DIR BUILD_DIR -j NUMBER_OF_PROCESSES where -j is the number of processes to run in parallel.

    If you want to create a LaTeX file, you can do so with $ pipenv run python -m sphinx SOURCE_DIR BUILD_DIR -b latex.

  3. Alternatively, you can have the documentation generated automatically with sphinx-autobuild. It can be installed with $ pipenv run python -m pip install sphinx-autobuild.

    The automatic creation can then be started with $ pipenv run python -m sphinx_autobuild SOURCE_DIR BUILD_DIR.

    This starts a local web server that provides the generated HTML pages at http://localhost:8000/. And every time you save changes in the Sphinx documentation, the corresponding HTML pages are regenerated and the browser view is updated.

    You can also use this to automatically generate the LaTeX output: $ pipenv run python -m sphinx_autobuild SOURCE_DIR BUILD_DIR -b latex.

  4. Another alternative is publication on readthedocs.org.

    To do this, you first have to create an account at https://readthedocs.org/ and then connect your GitLab, Github or Bitbucket account.

Markdown cells#

Equations

Equations can be specified inline between $ characters, for example

$\text{e}^{i\pi} = -1$

Equations can also be expressed line by line, for example

\begin{equation}
\int\limits_{-\infty}^\infty f(x) \delta(x - x_0) dx = f(x_0)
\end{equation}

See also

Quotes

nbsphinx supports the same syntax for quotations as nbconvert:

<cite data-cite="kluyver2016jupyter">Kluyver et al. (2016)</cite>
Alert boxes
<div class="alert alert-block alert-info">

**Note**

This is a notice!
</div>

<div class="alert alert-block alert-success">

**Success**

This is a success notice!
</div>

<div class="alert alert-block alert-warning">

**Warning**

This is a warning!
</div>

<div class="alert alert-block alert-danger">

**Danger**

This is a danger notice!
</div>
Links to other notebooks
a link to a notebook in a subdirectory](subdir/notebook-in-a-subdir.ipynb)
Links to *.rst files
[reStructuredText file](rst-file.rst)
Links to local files
[Pipfile](Pipfile)

Code cells#

Javascript

Javascript can be used for the generated HTML, for example:

%%javascript

var text = document.createTextNode("Hello, I was generated with JavaScript!");
// Content appended to "element" will be visible in the output area:
element.appendChild(text);

Galleries#

nbsphinx provides support for creating thumbnail galleries from a list of Jupyter notebooks. This functionality is based on Sphinx-Gallery and extends nbsphinx to work with Jupyter notebooks instead of Python scripts.

Sphinx-Gallery also directly supports Matplotlib, seaborn and Mayavi.

Installation#

Sphinx-Gallery can be installed for Sphinx ≥ 1.8.3 with

$ pipenv install sphinx-gallery

Configuration#

In order for Sphinx-Gallery to be used, it must also be entered into the conf.py file:

extensions = [
    "nbsphinx",
    "sphinx_gallery.load_style",
]

You can then use Sphinx-Gallery in two different ways:

  1. With the reStructuredText directive .. nbgallery::.

    See also

    Thumbnail Galleries

  2. In a Jupyter notebook, by adding an nbsphinx-gallery tag to the metadata of a cell:

    {
    "tags": [
        "nbsphinx-gallery"
    ]
}