This page was generated from doc/usage.ipynb. Interactive online version: Binder badge. Download notebook.

Usage

Project Setup

In the directory with your notebook files, run this command (assuming you have Sphinx and nbsphinx 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 make sure that the extensions setting at least contains 'nbsphinx' (but you might want to add other useful extensions as well):

extensions = [
    'nbsphinx',
]

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.

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.

Note

By default, notebooks will be executed during the Sphinx build process only if they do not have any output cells stored. See Controlling Notebook Execution.

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

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.

Note

If you want to execute notebooks (see Controlling Notebook Execution), you’ll need to install the appropriate Jupyter kernel. In the examples below, the IPython kernel is installed from the packet ipykernel.

Using requirements.txt

  1. Create a file named .readthedocs.yml in the main directory of your repository with the following contents:

    version: 2
    build:
      os: ubuntu-22.04
      tools:
        python: "3"
    python:
      install:
        - requirements: doc/requirements.txt
    

    For further options see https://docs.readthedocs.io/en/latest/config-file/.

  2. Create a file named doc/requirements.txt (or whatever you chose in the previous step) containing the required pip packages:

    ipykernel
    nbsphinx
    

    You can also install directly from Github et al., using a specific branch/tag/commit, e.g.

    git+https://github.com/spatialaudio/nbsphinx.git@master
    

Using conda

  1. Create a file named .readthedocs.yml in the main directory of your repository with the following contents:

    version: 2
    formats: all
    conda:
      environment: doc/environment.yml
    

    For further options see https://docs.readthedocs.io/en/latest/config-file/.

  2. Create a file named doc/environment.yml (or whatever you chose in the previous step) describing a conda environment like this:

    channels:
      - conda-forge
    dependencies:
      - python>=3
      - pandoc
      - ipykernel
      - pip
      - pip:
        - nbsphinx
    

    It is up to you if you want to install nbsphinx with conda or with pip (but note that the conda package might be outdated). And you can of course add further conda and pip packages. You can also install packages directly from Github et al., using a specific branch/tag/commit, e.g.

    - pip:
      - git+https://github.com/spatialaudio/nbsphinx.git@master
    

Note

The specification of the conda-forge channel is recommended because it tends to have more recent package versions than the default channel.

Automatic Creation of HTML and PDF output on GitLab Pages

When using GitLab pages, you can use nbsphinx by adding the file .gitlab-ci.yml to your repo and copying the following lines into this file:

image: python:3-slim

variables:
  PIP: python3 -m pip
  SPHINX: python3 -m sphinx -W --keep-going --color

build-docs:
  stage: build
  script:
    - apt-get update -y
    - apt-get install -y --no-install-recommends pandoc
    - $PIP install -r doc/requirements.txt
    - $SPHINX -d doctrees doc html -b html
    - $SPHINX -d doctrees doc linkcheck -b linkcheck
  artifacts:
    when: always
    paths:
      - html
      - linkcheck/output.*

pages:
  stage: deploy
  variables:
    GIT_STRATEGY: none
  script:
    - mv html public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

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)

Sphinx’s Built-In Themes

3rd-Party Themes

If you know of another Sphinx theme that should be included here, please open an issue on Github. An overview of many more themes can be found at https://sphinx-themes.org/.

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: