Configuration
The following configuration values can be used in the conf.py
file, see Project Setup.
Sphinx Configuration Values
All configuration values are described in the Sphinx documentation, here we mention only the ones which may be relevant in combination with nbsphinx
.
exclude_patterns
Sphinx builds all potential source files (reST files, Jupyter notebooks, …) that are in the source directory (including any sub-directories), whether you want to use them or not. If you want certain source files not to be built, specify them in exclude_patterns. For example, you might want to ignore source files in your build directory:
exclude_patterns = ['_build']
Note that the directory .ipynb_checkpoints
is automatically added to exclude_patterns
by nbsphinx
.
extensions
This is the only required value. You have to add 'nbsphinx'
to the list of extensions, otherwise it won’t work.
Other interesting extensions are:
'sphinx.ext.mathjax'
(Sphinx loads this by default) for math formulas'sphinxcontrib.bibtex'
for bibliographic references'sphinxcontrib.rsvgconverter'
for SVG->PDF conversion in LaTeX output'sphinx_copybutton'
for adding “copy to clipboard” buttons to all text/code boxes
html_css_files
See Custom CSS and html_css_files.
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
.
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:
html_sourcelink_suffix = ''
latex_additional_files
latex_additional_files can be useful if you are using BibTeX files, see References.
mathjax3_config
The configuration value mathjax3_config can be useful to enable Automatic Equation Numbering.
For Sphinx versions below 4.0.0, which used MathJax version 2, the relevant configuration value was called mathjax_config
.
pygments_style
Use pygments_style to change the color/font theme that’s used for syntax highlighting in source code.
This affects both code cells and code blocks in Markdown cells (unless overwritten by the html_theme).
suppress_warnings
Warnings can be really helpful to detect small mistakes, and you should consider invoking Sphinx with the -W option, which turns warnings into errors. However, warnings can also be annoying, especially if you are fully aware of the “problem”, but you simply don’t care about it for some reason. In this case, you can use suppress_warnings to silence specific types of warnings.
If you want to suppress all warnings from nbsphinx
, use this:
suppress_warnings = [
'nbsphinx',
]
You can also be more specific:
suppress_warnings = [
'nbsphinx.localfile',
'nbsphinx.gallery',
'nbsphinx.thumbnail',
'nbsphinx.notebooktitle',
'nbsphinx.ipywidgets',
]
nbsphinx
Configuration Values
nbsphinx_allow_errors
If True
, the build process is continued even if an exception occurs.
See Ignoring Errors.
nbsphinx_assume_equations
If False
, do not force loading MathJax on HTML pages generated from notebooks.
nbsphinx_codecell_lexer
Default Pygments lexer for syntax highlighting in code cells. If available, this information is taken from the notebook metadata instead.
nbsphinx_custom_formats
nbsphinx_epilog
See Prolog and Epilog.
nbsphinx_execute
Whether to execute notebooks before conversion or not. Possible values: 'always'
, 'never'
, 'auto'
(default).
nbsphinx_execute_arguments
Kernel arguments used when executing notebooks.
nbsphinx_input_prompt
Input prompt for code cells. %s
is replaced by the execution count.
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.
To get a prompt similar to the Classic Notebook, use
nbsphinx_output_prompt = 'Out[%s]:'
nbsphinx_prolog
See Prolog and Epilog.
nbsphinx_prompt_width
Width of input/output prompts (HTML only).
If a prompt is wider than that, it protrudes into the left margin.
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).
Any CSS length can be specified.
nbsphinx_thumbnails
A dictionary mapping from a document name (i.e. source file without suffix but with subdirectories) – optionally containing wildcards – to a thumbnail path to be used in a thumbnail gallery. Thumbnails specified in notebooks will override those provided in this dictionary.
nbsphinx_timeout
Controls when a cell will time out. The timeout is given in seconds. Given -1
, cells will never time out, which is also the default.
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).
If you use a local file, it should be located in a directory listed in html_static_path.
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.