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

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:

html_css_files

See Custom CSS and html_css_files.

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

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

See Explicitly Dis-/Enabling Notebook Execution.

nbsphinx_execute_arguments

Kernel arguments used when executing notebooks.

See Configuring the Kernels.

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'

See Configuring the Kernels.

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.

See Specifying Thumbnails.

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.

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

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.