This page was generated from doc/usage.ipynb. Interactive online version: .
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.
<Return>
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:
conf.py
extensions = [ 'nbsphinx', 'sphinx.ext.mathjax', ] exclude_patterns = ['_build', '**.ipynb_checkpoints']
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.
index.rst
.ipynb
doc/index.rst
All configuration values are described in the Sphinx documentation, here we mention only the ones which may be relevant in combination with nbsphinx.
nbsphinx
exclude_patterns
Sphinx builds all potential source files (reST files, Jupyter notebooks, …) that are in the source directory, whether they are linked to or not. If you want certain files not to be built, specify them in exclude_patterns. For example, you might want to ignore files in your build directory and temporary Jupyter files:
exclude_patterns = ['_build', '**.ipynb_checkpoints']
extensions
This is the only required value. You have to add 'nbsphinx' to the list of extensions, otherwise it won’t work.
'nbsphinx'
Other interesting extensions are:
'sphinx.ext.mathjax' for math formulas
'sphinx.ext.mathjax'
'sphinxcontrib.bibtex' for bibliographic references
'sphinxcontrib.bibtex'
'sphinxcontrib.rsvgconverter' for SVG->PDF conversion in LaTeX output
'sphinxcontrib.rsvgconverter'
'sphinx_copybutton' for adding “copy to clipboard” buttons to all text/code boxes
'sphinx_copybutton'
highlight_language
Default language for syntax highlighting in reST and Markdown cells, when no language is specified explicitly.
By default, this is 'python3', while Jupyter doesn’t have a default language. Set highlight_language to 'none' to get the same behavior as in Jupyter:
'python3'
'none'
highlight_language = 'none'
See also nbsphinx_codecell_lexer.
html_scaled_image_link
As a work-around – until https://github.com/sphinx-doc/sphinx/issues/4229 is solved – you should set html_scaled_image_link to False:
False
html_scaled_image_link = False
html_sourcelink_suffix
By default, a .txt suffix is added to source files. This is only relevant if the chosen HTML theme supports source links and if html_show_sourcelink is True.
.txt
True
Jupyter notebooks with the suffix .ipynb.txt are normally not very useful, so if you want to avoid the additional suffix, set html_sourcelink_suffix to the empty string:
.ipynb.txt
html_sourcelink_suffix = ''
latex_additional_files
latex_additional_files can be useful if you are using BibTeX files, see References.
mathjax_config
The configuration value mathjax_config can be useful to enable Automatic Equation Numbering.
nbsphinx_allow_errors
If True, the build process is continued even if an exception occurs.
See Ignoring Errors.
nbsphinx_codecell_lexer
Default Pygments lexer for syntax highlighting in code cells. If available, this information is taken from the notebook metadata instead.
Please note that this is not the same as highlight_language, which is used for formatting code in Markdown cells!
nbsphinx_custom_formats
See Custom Notebook Formats.
nbsphinx_epilog
See Prolog and Epilog.
nbsphinx_execute
Whether to execute notebooks before conversion or not. Possible values: 'always', 'never', 'auto' (default).
'always'
'never'
'auto'
See Explicitly Dis-/Enabling Notebook Execution.
nbsphinx_execute_arguments
Kernel arguments used when executing notebooks.
If you use Matplotlib for plots, this setting is recommended:
nbsphinx_execute_arguments = [ "--InlineBackend.figure_formats={'svg', 'pdf'}", "--InlineBackend.rc={'figure.dpi': 96}", ]
If you don’t use LaTeX/PDF output, you can drop the 'pdf' figure format.
'pdf'
See Configuring the Kernels.
nbsphinx_input_prompt
Input prompt for code cells. %s is replaced by the execution count.
%s
To get a prompt similar to the Classic Notebook, use
nbsphinx_input_prompt = 'In [%s]:'
nbsphinx_kernel_name
Use a different kernel than stored in the notebook metadata, e.g.:
nbsphinx_kernel_name = 'python3'
nbsphinx_output_prompt
Output prompt for code cells. %s is replaced by the execution count.
nbsphinx_output_prompt = 'Out[%s]:'
nbsphinx_prolog
nbsphinx_prompt_width
Width of input/output prompts (HTML only).
Any CSS length can be specified.
nbsphinx_requirejs_options
Options for loading RequireJS. See nbsphinx_requirejs_path.
nbsphinx_requirejs_path
URL or local path to override the default URL for RequireJS.
If you use a local file, it should be located in a directory listed in html_static_path.
Set to empty string to disable loading RequireJS.
nbsphinx_responsive_width
If the browser window is narrower than this, input/output prompts are on separate lines (HTML only).
nbsphinx_timeout
Controls when a cell will time out. Defaults to 30; use -1 for no timeout.
30
-1
See Cell Execution Timeout.
nbsphinx_widgets_options
Options for loading Jupyter widgets resources. See nbsphinx_widgets_path.
nbsphinx_widgets_path
URL or local path to override the default URL for Jupyter widgets resources. See Interactive Widgets (HTML only).
For loading the widgets resources, RequireJS is needed, see nbsphinx_requirejs_path.
If nbsphinx_widgets_path is not specified, widgets resources are only loaded if at least one notebook actually uses widgets. If you are loading the relevant JavaScript code by some other means already, you can set this option to the empty string to avoid loading it a second time.
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:
-j
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.
_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.
-E
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
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
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.
-f
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.
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.
ipykernel
requirements.txt
Create a file named .readthedocs.yml in the main directory of your repository with the following contents:
.readthedocs.yml
yaml version: 2 formats: all python: version: 3 install: - requirements: doc/requirements.txt system_packages: true
For further options see https://docs.readthedocs.io/en/latest/config-file/.
Create a file named doc/requirements.txt (or whatever you chose in the previous step) containing the required pip packages:
doc/requirements.txt
pip
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
conda
yaml version: 2 formats: all conda: file: doc/environment.yml
Create a file named doc/environment.yml (or whatever you chose in the previous step) describing a conda environment like this:
doc/environment.yml
yaml 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.
yaml - 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 default channel.
conda-forge
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:
The documentation (or the official sample page) of this theme (if available; see also the documentation of the built-in Sphinx themes)
How the nbsphinx documentation looks when using this theme
How to enable this theme using either requirements.txt or readthedocs.yml and theme-specific settings (in some cases)
readthedocs.yml
agogo: example, usage
agogo
alabaster: example, usage
bizstyle: example, usage
bizstyle
classic: example, usage
classic
haiku: example, usage
haiku
nature: example, usage
nature
pyramid: example, usage
pyramid
scrolls: example, usage
scrolls
sphinxdoc: example, usage
sphinxdoc
traditional: example, usage
traditional
alabaster_jupyterhub: example, usage
basicstrap: example, usage
better: example, usage
bootstrap: example, usage
bootstrap-astropy: example, usage
cloud/redcloud/greencloud: example, usage
guzzle_sphinx_theme: example, usage
julia: example, usage
jupyter: example, usage
maisie_sphinx_theme: example, usage
pandas_sphinx_theme: example, usage
pangeo: example, usage
press: example, usage
pytorch_sphinx_theme: example, usage
sizzle: example, usage
sphinx_material: example, usage
sphinx_py3doc_enhanced_theme: example, usage
sphinx_pyviz_theme: example, usage
sphinx_rtd_theme: example, usage
typlog: example, usage
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/.
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/