In the directory with your notebook files, run this command (assuming you have Sphinx installed already):
python3 -m sphinx.quickstart
Answer the questions that appear on the screen. In case of doubt, just
<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 those two variables contain the right things:
extensions = [ 'nbsphinx', 'sphinx.ext.mathjax', ] exclude_patterns = ['_build', '**.ipynb_checkpoints']
conf.py is in place, edit the file named
add the file names of your notebooks (with or without the
extension) to the
If you are using the
sphinx.ext.autosummary Sphinx extension,
there is a bug in Sphinx (below version
prevents notebooks from being parsed. As a work-around you can
explicitly list all the files for which autosummary should be ran
conf.py. For example,
autosummary_generate = ['myfile1.rst', 'myfile2.rst']
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
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
Subsequent builds will be faster, because only those source files which
have changed will be re-built. To force re-building all source files,
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
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
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 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 (under “Admin”, “Versions”) which of those should be created.
If your new versions are not automatically built, go to the “Settings” of your Github repository, continue to “Integrations & services”, and make sure that “ReadTheDocs” is listed and activated in the “Services” section. If not, use “Add service”. There is probably a similar thing for Bitbucket and others.
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
ist installed from the packet
Create a file named
requirements.txt(or whatever name you wish) in your repository containing the required pip packages:
sphinx>=1.4 ipykernel nbsphinx
You can also install directly from Github et al., using a specific branch/tag/commit, e.g.
In the “Advanced Settings” on readthedocs.org, specify the path to your
requirements.txtfile (or however you called it) in the box labeled “Requirements file”. Kinda obvious, isn’t it?
Still in the “Advanced Settings”, make sure the right Python interpreter is chosen. This must be the same version (2.x or 3.x) as you were using in your notebooks!
Create a file named
readthedocs.ymlin the main directory of your repository, containing the name of yet another file:
conda: file: readthedocs-environment.yml
Create the file mentioned above. You can choose whatever name you want (it may also live in a subdirectory, e.g.
doc/environment.yml), it just has to match whatever is specified in
readthedocs.yml. The second file describes a conda environment and should contain something like this:
channels: - conda-forge dependencies: - python==3.5 - sphinx>=1.4 - pandoc - nbconvert - ipykernel - pip: - nbsphinx
It is up to you if you want to install
pip(but note that the
condapackage might be outdated). And you can of course add further
pippackages. 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
The specification of the
conda-forge channel is recommended
because it tends to have more recent package versions than the
Most of the “Advanced Settings” on readthedocs.org will be ignored if
you have a
If you have a very long repository name (or branch name), you might run into this quite obscure problem: ‘placeholder too short’.
nbsphinx extension does not provide its own theme, you can use
any of the available themes or create a custom
if you feel like it.
The following (incomplete) list of themes contains up to three links for each theme:
- The documentation (or the official sample page) of this theme (if available; see also the documentation of the built-in Sphinx themes)
- How the
nbsphinxdocumentation looks when using this theme
- How to enable this theme using either
readthedocs.ymland theme-specific settings (in some cases)
Sphinx’s Built-In Themes¶
- sphinx_rtd_theme: example, usage
- bootstrap: example, usage
- cloud: example, usage
- sphinx_py3doc_enhanced_theme: example, usage
- basicstrap: example, usage
- dotted: example, usage
- better: example, usage
- guzzle_sphinx_theme: example, usage
- julia: example, usage
- jupyter: example, usage
Using Notebooks with Git¶
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
In the Jupyter Notebook application, you can manually clear all outputs by selecting “Cell” \(\to\) “All Output” \(\to\) “Clear” from the menu.
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: