.
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:
'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.