If you find bugs, errors, omissions or other things that need improvement, please create an issue or a pull request at Contributions are always welcome!

Development Installation#

Make sure that the necessary prerequisites are installed. Then, instead of pip-installing the latest release from PyPI, you should get the newest development version (a.k.a. “master”) with Git:

git clone
cd nbsphinx
python3 -m pip install -e .

… where -e stands for --editable.

When installing this way, you can quickly try other Git branches (in this example the branch is called “another-branch”):

git checkout another-branch

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

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

python3 build_sphinx

If you want to check the LaTeX output, use:

python3 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.

Building Themes#

The nbsphinx documentation is available in over 30 different HTML themes, with each having its own branch ending in -theme.

To simplify the building and testing of themes, which is especially needed when changing CSS, we provide you with command line tool to build all themes or a user specified subset. The tool is located at and can be run with:


Before doing that, the required dependencies can be obtained with:

python3 --requirements

This will create a list of dependencies in theme_comparison/theme_requirements.txt. The dependencies can then be installed with:

python3 -m pip install -r theme_comparison/theme_requirements.txt

If you just want to build a subset of the themes (e.g. alabaster and sphinx_rtd_theme), simply run:

python3 alabaster rtd

For more information run:

python3 --help


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 build_sphinx -W

This flag is also used for continuous integration on Github Actions (see the files .github/workflows/*.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.