Jupyter Notebook Tools for Sphinx¶

nbsphinx Packages¶

If you are using the conda package manager (e.g. with Anaconda for Linux/macOS/Windows), you can install nbsphinx from the conda-forge channel:

conda install -c conda-forge nbsphinx

If you are using Linux, there are packages available for many distributions.

On any platform, you can also install nbsphinx with pip, Python’s own package manager:

python3 -m pip install nbsphinx --user

If you want to install it system-wide for all users (assuming you have the necessary rights), just drop the --user flag.

To upgrade an existing nbsphinx installation to the newest release, use the --upgrade flag:

python3 -m pip install nbsphinx --upgrade --user

If you suddenly change your mind, you can un-install it with:

python3 -m pip uninstall nbsphinx

Depending on your Python installation, you may have to use python instead of python3.

nbsphinx Prerequisites¶

Some of the aforementioned packages will install some of these prerequisites automatically, some of the things may be already installed on your computer anyway.

conda install -c conda-forge sphinx

python3 -m pip install Sphinx --user

conda install -c conda-forge pandoc

conda install -c conda-forge ipython

python3 -m pip install IPython --user

conda install -c conda-forge ipykernel

python3 -m pip install ipykernel --user

Sphinx Setup¶

In the directory with your notebook files, run this command (assuming you have Sphinx installed already):

python3 -m sphinx.cmd.quickstart

Answer the questions that appear on the screen. In case of doubt, just press the <Return> key repeatedly 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 named conf.py. You should at least check if this variable contains the right things:

extensions = [
    'nbsphinx',
    'sphinx.ext.mathjax',
]

For an example, see this project’s conf.py file.

Once your conf.py is in place, edit the file named index.rst and add the file names of your notebooks (without the .ipynb extension) to the toctree directive. For an example, see this project’s doc/index.rst file.

Alternatively, you can delete the file index.rst and replace it with your own notebook called index.ipynb which will serve as main page. In this case you can create the main toctree in index.ipynb.

exclude_patterns = ['_build']

highlight_language = 'none'

html_sourcelink_suffix = ''

suppress_warnings = [
    'nbsphinx',
]

suppress_warnings = [
    'nbsphinx.localfile',
    'nbsphinx.gallery',
    'nbsphinx.thumbnail',
    'nbsphinx.notebooktitle',
    'nbsphinx.ipywidgets',
]

nbsphinx_execute_arguments = [
    "--InlineBackend.figure_formats={'svg', 'pdf'}",
    "--InlineBackend.rc={'figure.dpi': 96}",
]

nbsphinx_input_prompt = 'In [%s]:'

nbsphinx_kernel_name = 'python3'

nbsphinx_output_prompt = 'Out[%s]:'

Running Sphinx¶

To create the HTML pages, use this command:

python3 -m sphinx <source-dir> <build-dir>

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

python3 -m sphinx <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:

python3 -m sphinx . _build -j4

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

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.

To create LaTeX output, use:

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

If you don’t know how to create a PDF file from the LaTeX output, you should have a look at Latexmk (see also this tutorial).

Sphinx can automatically check if the links you are using are still valid. Just invoke it like this:

python3 -m sphinx <source-dir> <build-dir> -b linkcheck

Watching for Changes with sphinx-autobuild¶

If you think it’s tedious to run the Sphinx build command again and again while you make changes to your notebooks, you’ll be happy to hear that there is a way to avoid that: sphinx-autobuild!

It can be installed with

python3 -m pip install sphinx-autobuild --user

You can start auto-building your files with

python3 -m sphinx_autobuild <source-dir> <build-dir>

This will start a local webserver which will serve the generated HTML pages at http://localhost:8000/. Whenever you save changes in one of your notebooks, the appropriate HTML page(s) will be re-built and when finished, your browser view will be refreshed automagically. Neat!

You can also abuse this to auto-build the LaTeX output:

python3 -m sphinx_autobuild <source-dir> <build-dir> -b latex

However, to auto-build the final PDF file as well, you’ll need an additional tool. Again, you can use latexmk for this (see above). Change to the build directory and run

latexmk -pdf -pvc

If your PDF viewer isn’t opened because of LaTeX build errors, you can use the command line flag -f to force creating a PDF file.

Automatic Creation of HTML and PDF output on readthedocs.org¶

There are two different methods, both of which are described below.

In both cases, you’ll first have to create an account on https://readthedocs.org/ and connect your GitLab/Github/Bitbucket/… account. Instead of connecting, you can also manually add any publicly available Git/Subversion/Mercurial/Bazaar/… repository.

After doing the steps described below, you only have to “push” to your repository, and the HTML pages and the PDF file of your stuff are automagically created on readthedocs.org. Awesome!

You can even have different versions of your stuff, just use Git tags and branches and select in the readthedocs.org settings which of those should be created.

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.

The following (incomplete) list of themes contains up to three links for each theme:

1. The documentation (or the official sample page) of this theme (if available; see also the documentation of the built-in Sphinx themes)

2. How the nbsphinx documentation looks when using this theme

3. How to enable this theme using either requirements.txt or readthedocs.yml and theme-specific settings (in some cases)

Using Notebooks with Git¶

Git is extremely useful for managing source code and it can and should also be used for managing Jupyter notebooks. There is one caveat, however: Notebooks can contain output cells with rich media like images, plots, sounds, HTML, JavaScript and many other types of bulky machine-created content. This can make it hard to work with Git efficiently, because changes in those bulky contents can completely obscure the more interesting human-made changes in text and source code. Working with multiple collaborators on a notebook can become very tedious because of this.

It is therefore highly recommended that you remove all outputs from your notebooks before committing changes to a Git repository (except for the reasons mentioned in Pre-Executing Notebooks).

If there are no output cells in a notebook, nbsphinx will by default execute the notebook, and the pages generated by Sphinx will therefore contain all the output cells. See Controlling Notebook Execution for how this behavior can be customized.

In the Jupyter Notebook application, you can manually clear all outputs by selecting “Cell” \(\to\) “All Output” \(\to\) “Clear” from the menu. In JupyterLab, the menu items are “Edit” \(\to\) “Clear All Outputs”.

There are several tools available to remove outputs from multiple files at once without having to open them separately. You can even include such a tool as “clean/smudge filters” into your Git workflow, which will strip the output cells automatically whenever a Git command is executed. For details, have a look at those links:

• https://github.com/kynan/nbstripout

• https://github.com/toobaz/ipynb_output_filter

• https://tillahoffmann.github.io/2017/04/17/versioning-jupyter-notebooks-with-git.html

• http://timstaley.co.uk/posts/making-git-and-jupyter-notebooks-play-nice/

• https://pascalbugnion.net/blog/ipython-notebooks-and-git.html

• https://github.com/choldgraf/nbclean

• https://jamesfolberth.org/articles/2017/08/07/git-commit-hook-for-jupyter-notebooks/

Equations¶

Inline equations like \(\text{e}^{i\pi} = -1\) can be created by putting a LaTeX expression between two dollar signs, like this: $\text{e}^{i\pi} = -1$.

ERROR: Unknown interpreted text role "raw-latex".

Equations can also be displayed on their own line like this:

This can be done by simply using one of the LaTeX math environments, like so:

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

extensions = [
    'nbsphinx',
    'sphinx.ext.mathjax',
    # ... other useful extensions ...
]

mathjax_config = {
    'TeX': {'equationNumbers': {'autoNumber': 'AMS', 'useLabelIds': True}},
}

\begin{equation}
\phi = \frac{1 + \sqrt{5}}{2}
\label{golden-mean}
\end{equation}

\begin{equation}
a^2 + b^2 = c^2
\tag{99.4}
\label{pythagoras}
\end{equation}

Citations¶

According to https://nbconvert.readthedocs.io/en/latest/latex_citations.html, nbconvert supports citations using a special HTML-based syntax. nbsphinx supports the same syntax.

Example: [KRKP+16].

<cite data-cite="kluyver2016jupyter">Kluyver et al. (2016)</cite>

You don’t actually have to use <cite>, any inline HTML tag can be used, e.g. <strong>: [PGH11].

<strong data-cite="perez2011python">Python: An Ecosystem for Scientific Computing</strong>

You’ll also have to define a list of references, see the section about references.

There is also a Notebook extension which may or may not be useful: https://github.com/takluyver/cite2c.

Code¶

We can also write code with nice syntax highlighting:

print("Hello, world!")

Tables¶

Images¶

Local image:

![Jupyter notebook icon](images/notebook_icon.png)

Remote image:

![Python logo (remote)](https://www.python.org/static/img/python-logo-large.png)

<img src="images/notebook_icon.png" alt="Jupyter notebook icon" width="300">

![Python logo](images/python_logo.svg)

![Jupyter logo](https://jupyter.org/assets/main-logo.svg)

Cell Attachments¶

Images can also be embedded in the notebook itself. Just drag an image file into the Markdown cell you are just editing or copy and paste some image data from an image editor/viewer.

The generated Markdown code will look just like a “normal” image link, except that it will have an attachment: prefix:

![a stick figure](attachment:stickfigure.png)

This is a cell attachment:

In the Jupyter Notebook, there is a speciall “Attachments” cell toolbar which you can use to see all attachments of a cell and delete them, if needed.

HTML Elements (HTML only)¶

It is allowed to use plain HTML elements within Markdown cells. Those elements are passed through to the HTML output and are ignored for the LaTeX output. Below are a few examples.

HTML5 audio elements can be created like this:

<audio src="https://example.org/audio.ogg" controls>alternative text</audio>

Example:

HTML5 video elements can be created like this:

<video src="https://example.org/video.ogv" controls>alternative text</video>

Example:

The alternative text is shown in browsers that don’t support those elements. The same text is also shown in Sphinx’s LaTeX output.

Info/Warning Boxes¶

Until there is an info/warning extension for Markdown/CommonMark (see this issue), such boxes can be created by using HTML <div> elements like this:

<div class="alert alert-info">

Note

This is a note!

</div>

For this to work reliably, you should obey the following guidelines:

• The class attribute has to be either "alert alert-info" or "alert alert-warning", other values will not be converted correctly.

• No further attributes are allowed.

• For compatibility with CommonMark, you should add an empty line between the <div> start tag and the beginning of the content.

Links to Other Notebooks¶

Relative links to local notebooks can be used: a link to a notebook in a subdirectory, a link to an orphan notebook (latter won’t work in LaTeX output, because orphan pages are not included there).

This is how a link is created in Markdown:

[a link to a notebook in a subdirectory](subdir/a-notebook-in-a-subdir.ipynb)

Markdown also supports reference-style links: a reference-style link, another version of the same link.

These can be created with this syntax:

[a reference-style link][mylink]

[mylink]: subdir/a-notebook-in-a-subdir.ipynb

Links to sub-sections are also possible, e.g. this subsection.

This link was created with:

[this subsection](subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section)

You just have to remember to replace spaces with hyphens!

BTW, links to sections of the current notebook work, too, e.g. beginning of this section.

This can be done, as expected, like this:

[beginning of this section](#Links-to-Other-Notebooks)

It’s also possible to create a link to the beginning of the current page, by simply using a # character:

[link to the beginning of the current page](#)

Links to *.rst Files (and Other Sphinx Source Files)¶

Links to files whose extension is in the configuration value source_suffix, will be converted to links to the generated HTML/LaTeX pages. Example: A reStructuredText file.

This was created with:

[A reStructuredText file](a-normal-rst-file.rst)

Links to sub-sections are also possible. Example: Sphinx Directives.

This was created with:

[Sphinx Directives](a-normal-rst-file.rst#sphinx-directives-for-info-warning-boxes)

Links to Local Files¶

Links to local files (other than Jupyter notebooks and other Sphinx source files) are also possible, e.g. requirements.txt.

This was simply created with:

[requirements.txt](requirements.txt)

The linked files are automatically copied to the HTML output directory. For LaTeX output, links are created, but the files are not copied to the target directory.

Links to Domain Objects¶

Links to Sphinx domain objects (such as a Python class or JavaScript function) are also possible. For example: example_python_function().

This was created with:

[example_python_function()](a-normal-rst-file.rst#example_python_function)

This is especially useful for use with the Sphinx autodoc extension!

Code, Output, Streams¶

An empty code cell:

[ ]:

Two empty lines:

[ ]:

Leading/trailing empty lines:

[1]:

# 2 empty lines before, 1 after

A simple output:

[2]:

6 * 7

[2]:

42

The standard output stream:

[3]:

print('Hello, world!')

Hello, world!

Normal output + standard output

[4]:

print('Hello, world!')
6 * 7

Hello, world!

[4]:

42

The standard error stream is highlighted and displayed just below the code cell. The standard output stream comes afterwards (with no special highlighting). Finally, the “normal” output is displayed.

[5]:

import sys

print("I'll appear on the standard error stream", file=sys.stderr)
print("I'll appear on the standard output stream")
"I'm the 'normal' output"

I'll appear on the standard output stream

I'll appear on the standard error stream

[5]:

"I'm the 'normal' output"

Cell Magics¶

IPython can handle code in other languages by means of cell magics:

[6]:

%%bash
for i in 1 2 3
do
    echo $i
done

1
2
3

Special Display Formats¶

See IPython example notebook.

Local Image Files¶

[7]:

from IPython.display import Image
i = Image(filename='images/notebook_icon.png')
i

[7]:

[8]:

display(i)

See also SVG support for LaTeX.

[9]:

from IPython.display import SVG
SVG(filename='images/python_logo.svg')

[9]:

Image URLs¶

[10]:

Image(url='https://www.python.org/static/img/python-logo-large.png')

[10]:

[11]:

Image(url='https://www.python.org/static/img/python-logo-large.png', embed=True)

[11]:

[12]:

Image(url='https://jupyter.org/assets/nav_logo.svg')

[12]:

[13]:

from IPython.display import Math
eq = Math(r'\int\limits_{-\infty}^\infty f(x) \delta(x - x_0) dx = f(x_0)')
eq

[13]:

[14]:

display(eq)

[15]:

from IPython.display import Latex
Latex(r'This is a \LaTeX{} equation: $a^2 + b^2 = c^2$')

[15]:

[16]:

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

Plots¶

The output formats for Matplotlib plots can be customized. You’ll need separate settings for the Jupyter Notebook application and for nbsphinx.

If you want to use SVG images for Matplotlib plots, add this line to your IPython configuration file:

c.InlineBackend.figure_formats = {'svg'}

If you want SVG images, but also want nice plots when exporting to LaTeX/PDF, you can select:

c.InlineBackend.figure_formats = {'svg', 'pdf'}

If you want to use the default PNG plots or HiDPI plots using 'png2x' (a.k.a. 'retina'), make sure to set this:

c.InlineBackend.rc = {'figure.dpi': 96}

This is needed because the default 'figure.dpi' value of 72 is only valid for the Qt Console.

If you are planning to store your SVG plots as part of your notebooks, you should also have a look at the 'svg.hashsalt' setting.

For more details on these and other settings, have a look at Default Values for Matplotlib’s “inline” Backend.

The configuration file ipython_kernel_config.py can be either in the directory where your notebook is located (see the ipython_kernel_config.py in this directory), or in your profile directory (typically ~/.ipython/profile_default/ipython_kernel_config.py). To find out your IPython profile directory, use this command:

python3 -m IPython profile locate

A local ipython_kernel_config.py in the notebook directory also works on https://mybinder.org/. Alternatively, you can create a file with those settings in a file named .ipython/profile_default/ipython_kernel_config.py in your repository.

To get SVG and PDF plots for nbsphinx, use something like this in your conf.py file:

nbsphinx_execute_arguments = [
    "--InlineBackend.figure_formats={'svg', 'pdf'}",
    "--InlineBackend.rc={'figure.dpi': 96}",
]

In the following example, nbsphinx should use an SVG image in the HTML output and a PDF image for LaTeX/PDF output.

[17]:

import matplotlib.pyplot as plt

[18]:

fig, ax = plt.subplots(figsize=[6, 3])
ax.plot([4, 9, 7, 20, 6, 33, 13, 23, 16, 62, 8]);

Alternatively, the figure format(s) can also be chosen directly in the notebook (which overrides the setting in nbsphinx_execute_arguments and in the IPython configuration):

[19]:

%config InlineBackend.figure_formats = ['png']

[20]:

fig

[20]:

If you want to use PNG images, but with HiDPI resolution, use the special 'png2x' (a.k.a. 'retina') format (which also looks nice in the LaTeX output):

[21]:

%config InlineBackend.figure_formats = ['png2x']

[22]:

fig

[22]:

[23]:

import numpy as np
import pandas as pd

[24]:

df = pd.DataFrame(np.random.randint(0, 100, size=[5, 4]),
                  columns=['a', 'b', 'c', 'd'])
df

[24]:

[25]:

pd.set_option('display.latex.repr', True)

\usepackage{booktabs}

[26]:

pd.set_option('display.latex.longtable', True)

[27]:

pd.set_option('display.latex.escape', False)

[28]:

df = pd.DataFrame(np.random.randint(0, 100, size=[10, 4]),
                  columns=[r'$\alpha$', r'$\beta$', r'$\gamma$', r'$\delta$'])
df

[28]:

[29]:

from IPython.display import YouTubeVideo
YouTubeVideo('WAikxUGbomY')

[29]:

[30]:

import ipywidgets as w

[31]:

slider = w.IntSlider()
slider.value = 42
slider

[32]:

slider

[33]:

link = w.IntSlider(description='link')
w.link((slider, 'value'), (link, 'value'))
jslink = w.IntSlider(description='jslink')
w.jslink((slider, 'value'), (jslink, 'value'))
dlink = w.IntSlider(description='dlink')
w.dlink((slider, 'value'), (dlink, 'value'))
jsdlink = w.IntSlider(description='jsdlink')
w.jsdlink((slider, 'value'), (jsdlink, 'value'))
w.VBox([link, jslink, dlink, jsdlink])

[34]:

%%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);

[35]:

display({
    'text/x-python': 'print("Hello, world!")',
    'text/x-haskell': 'main = putStrLn "Hello, world!"',
}, raw=True)

ANSI Colors¶

The standard output and standard error streams may contain ANSI escape sequences to change the text and background colors.

[36]:

print('BEWARE: \x1b[1;33;41mugly colors\x1b[m!', file=sys.stderr)
print('AB\x1b[43mCD\x1b[35mEF\x1b[1mGH\x1b[4mIJ\x1b[7m'
      'KL\x1b[49mMN\x1b[39mOP\x1b[22mQR\x1b[24mST\x1b[27mUV')

ABCDEFGHIJKLMNOPQRSTUV

BEWARE: ugly colors!

The following code showing the 8 basic ANSI colors is based on http://tldp.org/HOWTO/Bash-Prompt-HOWTO/x329.html. Each of the 8 colors has an “intense” variation, which is used for bold text.

[37]:

text = ' XYZ '
formatstring = '\x1b[{}m' + text + '\x1b[m'

print(' ' * 6 + ' ' * len(text) +
      ''.join('{:^{}}'.format(bg, len(text)) for bg in range(40, 48)))
for fg in range(30, 38):
    for bold in False, True:
        fg_code = ('1;' if bold else '') + str(fg)
        print(' {:>4} '.format(fg_code) + formatstring.format(fg_code) +
              ''.join(formatstring.format(fg_code + ';' + str(bg))
                      for bg in range(40, 48)))

            40   41   42   43   44   45   46   47
   30  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
 1;30  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
   31  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
 1;31  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
   32  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
 1;32  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
   33  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
 1;33  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
   34  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
 1;34  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
   35  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
 1;35  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
   36  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
 1;36  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
   37  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 
 1;37  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ  XYZ 

ANSI also supports a set of 256 indexed colors. The following code showing all of them is based on http://bitmote.com/index.php?post/2012/11/19/Using-ANSI-Color-Codes-to-Colorize-Your-Bash-Prompt-on-Linux.

[38]:

formatstring = '\x1b[38;5;{0};48;5;{0}mX\x1b[1mX\x1b[m'

print('  + ' + ''.join('{:2}'.format(i) for i in range(36)))
print('  0 ' + ''.join(formatstring.format(i) for i in range(16)))
for i in range(7):
    i = i * 36 + 16
    print('{:3} '.format(i) + ''.join(formatstring.format(i + j)
                                      for j in range(36) if i + j < 256))

  +  0 1 2 3 4 5 6 7 8 91011121314151617181920212223242526272829303132333435
  0 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 16 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 52 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 88 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
124 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
160 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
196 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
232 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

You can even use 24-bit RGB colors:

[39]:

start = 255, 0, 0
end = 0, 0, 255
length = 79
out = []

for i in range(length):
    rgb = [start[c] + int(i * (end[c] - start[c]) / length) for c in range(3)]
    out.append('\x1b['
               '38;2;{rgb[2]};{rgb[1]};{rgb[0]};'
               '48;2;{rgb[0]};{rgb[1]};{rgb[2]}mX\x1b[m'.format(rgb=rgb))
print(''.join(out))

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Usage¶

To select a desired format from within Jupyter, select the cell containing your special code and choose options from the following dropdown menus:

1. Select “Raw NBConvert”

2. Switch the Cell Toolbar to “Raw Cell Format”

3. Chose the appropriate “Raw NBConvert Format” within the cell

Available Raw Cell Formats¶

The following examples show how different Jupyter cell formats are rendered by Sphinx.

Examples¶

You can include a simple static string, using reST markup if you like:

nbsphinx_epilog = """
----

Generated by nbsphinx_ from a Jupyter_ notebook.

.. _nbsphinx: https://nbsphinx.readthedocs.io/
.. _Jupyter: https://jupyter.org/
"""

Using some additional Jinja2 markup and the information from the env variable, you can create URLs that point to the current notebook file, but located on some other server:

nbsphinx_prolog = """
Go there: https://example.org/notebooks/{{ env.doc2path(env.docname, base=None) }}

----
"""

You can also use separate content for HTML and LaTeX output, e.g.:

nbsphinx_prolog = r"""
{% set docname = env.doc2path(env.docname, base=None) %}

.. only:: html

    Go there: https://example.org/notebooks/{{ docname }}

.. raw:: latex

    \nbsphinxstartnotebook{The following section was created from
    \texttt{\strut{}{{ docname }}}:}
"""

nbsphinx_epilog = r"""
.. raw:: latex

    \nbsphinxstopnotebook{\hfill End of notebook.}
"""

Note the use of the \nbsphinxstartnotebook and \nbsphinxstopnotebook commands. Those make sure there is not too much space between the “prolog” and the beginning of the notebook and, respectively, between the end of the notebook and the “epilog”. They also avoid page breaks, in order for the “prolog”/”epilog” not to end up on the page before/after the notebook.

For a more involved example for different HTML and LaTeX versions, see the file conf.py of the nbsphinx documentation.

Example: Jupytext¶

One example for a library which provides a custom conversion function is jupytext, which allows storing the contents of Jupyter notebooks in Markdown and R-Markdown, as well as plain Julia, Python and R files.

Since its conversion function takes more than a single string argument, we have to pass a keyword argument, e.g.:

nbsphinx_custom_formats = {
    '.Rmd': ['jupytext.reads', {'fmt': 'Rmd'}],
}

This very page is an example of a notebook stored in the py:percent format (see docs):

[1]:

!head -20 custom-formats.pct.py

# %% [markdown]
# # Custom Notebook Formats
#
# By default, Jupyter notebooks are stored in files with the suffix `.ipynb`,
# which use the JSON format for storage.
#
# However, there are libraries available which allow storing notebooks
# in different formats, using different file suffixes.
#
# To use a custom notebook format in `nbsphinx`, you can specify the
# `nbsphinx_custom_formats` option in your `conf.py` file.
# You have to provide the file extension
# and a conversion function that takes the contents of a file (as a string)
# and returns a Jupyter notebook object.
#
# ```python
# nbsphinx_custom_formats = {
#     '.mysuffix': 'mylibrary.converter_function',
# }
# ```

To select a suitable conversion function, we use the following setting in conf.py:

nbsphinx_custom_formats = {
    '.pct.py': ['jupytext.reads', {'fmt': 'py:percent'}],
}

Another example is this gallery example page.

A Sub-Section¶

This is just for testing inter-notebook links, see this section.

For All Pages¶

Just create your own CSS file, e.g. my-own-style.css, and put it into the _static/ sub-directory of your source directory.

You’ll also have to set the config values html_static_path and html_css_files in your conf.py, e.g. like this:

html_static_path = ['_static']
html_css_files = ['my-own-style.css']

For All RST files¶

If you want your style to only apply to *.rst files (and not Jupyter notebooks or other source files), you can use rst_prolog with the raw directive in your conf.py like this:

rst_prolog = """
.. raw:: html

    <style>
        h1 {
            color: fuchsia;
        }
    </style>
"""

For All Notebooks¶

Similarly, if you want your style to only apply to notebooks, you can use nbsphinx_prolog like this:

nbsphinx_prolog = """
.. raw:: html

    <style>
        h1 {
            color: chartreuse;
        }
    </style>
"""

For a Single Notebook¶

For styles that should affect only the current notebook, you can simply insert <style> tags into Markdown cells like this:

<style>
    .nbinput .prompt,
    .nboutput .prompt {
        display: none;
    }
</style>

This CSS example removes the input and output prompts from code cells, see the following cell:

[1]:

6 * 7

[1]:

42

Links to Notebooks (and Other Sphinx Source Files)¶

Links to Sphinx source files can be created like normal Sphinx hyperlinks, just using a relative path to the local file: link.

using a relative path to the local file: link_.

.. _link: subdir/a-notebook-in-a-subdir.ipynb

If the link text has a space (or some other strange character) in it, you have to surround it with backticks: a notebook link.

surround it with backticks: `a notebook link`_.

.. _a notebook link: subdir/a-notebook-in-a-subdir.ipynb

You can also use an anonymous hyperlink target, like this: link. If you have multiple of those, their order matters!

like this: link__.

__ subdir/a-notebook-in-a-subdir.ipynb

Finally, you can use Embedded URIs, like this link.

like this `link <subdir/a-notebook-in-a-subdir.ipynb>`_.

Links to subsections are also possible by adding a hash sign (#) and the section title to any of the above-mentioned link variants. You have to replace spaces in the section titles by hyphens. For example, see this subsection.

For example, see this subsection_.

.. _subsection: subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section

Links to Notebooks, Ye Olde Way¶

In addition to the way shown above, you can also create links to notebooks (and other Sphinx source files) with :ref:. This has some disadvantages:

• It is arguably a bit more clunky.

• Because :ref: is a Sphinx feature, the links don’t work on Github and other rendered reStructuredText pages that use plain old docutils.

It also has one important advantage:

• The link text can automatically be taken from the actual section title.

A link with automatic title looks like this: Notebooks in Sub-Directories.

:ref:`/subdir/a-notebook-in-a-subdir.ipynb`

But you can also provide your own link title.

:ref:`your own link title </subdir/a-notebook-in-a-subdir.ipynb>`

However, if you want to use your own title, you are probably better off using the method described above in Links to Notebooks (and Other Sphinx Source Files).

Links to subsections are also possible, e.g. A Sub-Section (the subsection title is used as link text) and alternative text.

These links were created with:

:ref:`/subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section`
:ref:`alternative text </subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section>`

Sphinx Directives for Info/Warning Boxes¶

With a bit of luck, it will be possible (some time in the future) to create info/warning boxes in Markdown cells, see https://github.com/jupyter/notebook/issues/1292. If this ever happens, nbsphinx will provide directives for creating such boxes. For now, there are two directives available: nbinfo and nbwarning. This is how an info box looks like:

Domain Objects¶

example_python_function(foo)¶

This is just for testing domain object links. See this section.

Parameters

foo (str) – Example string parameter

Citations¶

You could use standard Sphinx citations, but it might be more practical to use the sphinxcontrib.bibtex extension.

If you install and enable this extension, you can create citations like [PGH11]:

:cite:`perez2011python`

You can create similar citations in Jupyter notebooks with a special HTML syntax, see the section about citations in Markdown cells.

For those citations to work, you also need to specify a BibTeX file, as explained in the next section.

References¶

After installing and enabling the sphinxcontrib.bibtex extension, you can create a list of references from a BibTeX file like this:

.. bibliography:: references.bib

Have a look at the documentation for all the available options.

The list of references may look something like this (in HTML output):

KRKP+16

Thomas Kluyver, Benjamin Ragan-Kelley, Fernando Pérez, Brian Granger, Matthias Bussonnier, Jonathan Frederic, Kyle Kelley, Jessica Hamrick, Jason Grout, Sylvain Corlay, Paul Ivanov, Damián Avila, Safia Abdalla, Carol Willing, and Jupyter Development Team. Jupyter Notebooks—a publishing format for reproducible computational workflows. In Fernando Loizides and Birgit Schmidt, editors, Positioning and Power in Academic Publishing: Players, Agents and Agendas, pages 87–90. IOS Press, 2016. doi:10.3233/978-1-61499-649-1-87.

PGH11

Fernando Pérez, Brian E. Granger, and John D. Hunter. Python: an ecosystem for scientific computing. Computing in Science Engineering, 13(2):13–21, 2011. doi:10.1109/MCSE.2010.119.

However, in the LaTeX/PDF output the list of references will not appear here, but at the end of the document. For a possible work-around, see https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/156.

There is an alternative Sphinx extension for creating bibliographies: https://bitbucket.org/wnielson/sphinx-natbib/. However, this project seems to be abandoned (last commit in 2011).

Thumbnail Galleries¶

With nbsphinx you can create thumbnail galleries in notebook files as described in Creating Thumbnail Galleries.

If you like, you can also create such galleries in reST files using the nbgallery directive.

It takes the same parameters as the toctree directive.

The following example gallery was created using:

.. nbgallery::
    :caption: This is a thumbnail gallery:
    :name: rst-gallery
    :glob:
    :reversed:

    gallery/*-rst

This page was generated from doc/gallery/uno-rst.ipynb. Interactive online version: .

Dummy Notebook 1 for Gallery¶

This is a dummy file just to fill the gallery in the reST file.

The thumbnail image is assigned in conf.py.

This page was generated from doc/gallery/due-rst.pct.py. Interactive online version: .

Dummy Notebook 2 for Gallery¶

This is a dummy file just to fill the gallery in the reST file.

The thumbnail image is assigned in conf.py.

The source file is, for no particular reason, a Python script adhering to the py:percent format. It is parsed with the help of Jupytext, see Custom Notebook Formats.

[1]:

from pathlib import Path

[2]:

filename = 'due-rst.pct.py'

print(Path(filename).read_text())

# %% [markdown]
# # Dummy Notebook 2 for Gallery
#
# This is a dummy file just to fill
# [the gallery in the reST file](../a-normal-rst-file.rst#thumbnail-galleries).
#
# The thumbnail image is assigned in [conf.py](../conf.py).

# %% [markdown]
# The source file is, for no particular reason,
# a Python script adhering to the `py:percent` format.
# It is parsed with the help of [Jupytext](https://jupytext.readthedocs.io/),
# see [Custom Notebook Formats](../custom-formats.ipynb).

# %%
from pathlib import Path

# %%
filename = 'due-rst.pct.py'

print(Path(filename).read_text())

Development Installation¶

Instead of pip-installing the latest release from PyPI, you should get the newest development version (a.k.a. “master”) from Github:

git clone https://github.com/spatialaudio/nbsphinx.git
cd nbsphinx
python3 -m pip install -e . --user

This way, your installation always stays up-to-date, even if you pull new changes from the Github repository. If you have only Python 3 installed, you might have to use the command python instead of python3. When installing nbsphinx this way, you can also quickly check other Git branches (in this example the branch is called “another-branch”):

git checkout another-branch

When you run Sphinx now, it automatically uses the version “another-branch” of nbsphinx. If you want to go back to the “master” branch, use:

git checkout master

To get the latest changes from Github, use:

git pull --ff-only

Building the Documentation¶

If you make changes to the documentation, you should create the HTML pages locally using Sphinx and check if they look OK.

Initially, you might need to install a few packages that are needed to build the documentation:

python3 -m pip install -r doc/requirements.txt --user

To (re-)build the HTML files, use:

python3 setup.py build_sphinx

If you want to check the LaTeX output, use:

python3 setup.py build_sphinx -b latex

Again, you’ll probably have to use python instead of python3. The generated files will be available in the directories build/sphinx/html/ and build/sphinx/latex/, respectively.

Testing¶

Unfortunately, the currently available automated tests are very limited. Contributions to improve the testing situation are of course also welcome!

The nbsphinx documentation also serves as a test case. However, the resulting HTML/LaTeX/PDF files have to be inspected manually to check whether they look as expected.

Sphinx’s warnings can help spot problems, therefore it is recommended to use the -W flag to turn Sphinx warnings into errors while testing:

python3 setup.py build_sphinx -W

This flag is also used for continuous integration on Travis-CI (see the file .travis.yml) and CircleCI (see the file .circleci/config.yml).

Sphinx has a linkcheck builder that can check whether all URLs used in the documentation are still valid. This is also part of the continuous integration setup on CircelCI.