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 python3 -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, e.g. 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, e.g.

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, e.g.

{
 "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 Python4DataScience/workspace/ipython/index.rst.

  2. Finally, you can generate the pages, e.g. HTML with

    $ pipenv run python3 -m sphinx <source-dir> <build-dir>

    or

    $ pipenv run python3 -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 python3 -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 python3 -m pip install sphinx-autobuild

    The automatic creation can then be started with

    $ pipenv run python3 -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 python3 -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, e.g.

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

Equations can also be expressed line by line e.g.

\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>
Info and warning boxes
<div class="alert alert-info">
**Note:** This is a note!
</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, e.g .:

%%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"
    ]
}