doc/configuration.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": "hidden"
   },
   "source": [
    "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Configuration\n",
    "\n",
    "The following configuration values\n",
    "can be used in the `conf.py` file,\n",
    "see [Project Setup](usage.ipynb#Project-Setup)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sphinx Configuration Values\n",
    "\n",
    "All configuration values are described in the\n",
    "[Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/configuration.html),\n",
    "here we mention only the ones which may be relevant\n",
    "in combination with `nbsphinx`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `exclude_patterns`\n",
    "\n",
    "Sphinx builds all potential source files (reST files, Jupyter notebooks, ...)\n",
    "that are in the source directory (including any sub-directories),\n",
    "whether you want to use them or not.\n",
    "If you want certain source files not to be built,\n",
    "specify them in\n",
    "[exclude_patterns](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-exclude_patterns).\n",
    "For example, you might want to ignore source files in your build directory:\n",
    "\n",
    "```python\n",
    "exclude_patterns = ['_build']\n",
    "```\n",
    "\n",
    "Note that the directory `.ipynb_checkpoints`\n",
    "is automatically added\n",
    "to `exclude_patterns`\n",
    "by `nbsphinx`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `extensions`\n",
    "\n",
    "This is the only required value.\n",
    "You have to add `'nbsphinx'` to the list of\n",
    "[extensions](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-extensions),\n",
    "otherwise it won't work.\n",
    "\n",
    "Other interesting extensions are:\n",
    "\n",
    "* `'sphinx.ext.mathjax'` (Sphinx loads this by default)\n",
    "  for [math formulas](markdown-cells.ipynb#Equations)\n",
    "* `'sphinxcontrib.bibtex'`\n",
    "  for [bibliographic references](a-normal-rst-file.rst#references)\n",
    "* `'sphinxcontrib.rsvgconverter'`\n",
    "  for [SVG->PDF conversion in LaTeX output](markdown-cells.ipynb#SVG-support-for-LaTeX)\n",
    "* `'sphinx_copybutton'`\n",
    "  for [adding \"copy to clipboard\" buttons](https://sphinx-copybutton.readthedocs.io/)\n",
    "  to all text/code boxes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `html_css_files`\n",
    "\n",
    "See [Custom CSS](custom-css.ipynb) and\n",
    "[html_css_files](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `html_sourcelink_suffix`\n",
    "\n",
    "\n",
    "By default, a `.txt` suffix is added to source files.\n",
    "This is only relevant if the chosen HTML theme supports source links and if\n",
    "[html_show_sourcelink](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_show_sourcelink)\n",
    "is `True`.\n",
    "\n",
    "Jupyter notebooks with the suffix `.ipynb.txt` are normally not very useful,\n",
    "so if you want to avoid the additional suffix, set\n",
    "[html_sourcelink_suffix](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sourcelink_suffix) to the empty string:\n",
    "\n",
    "```python\n",
    "html_sourcelink_suffix = ''\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `latex_additional_files`\n",
    "\n",
    "[latex_additional_files](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-latex_additional_files)\n",
    "can be useful if you are using BibTeX files, see\n",
    "[References](a-normal-rst-file.rst#references)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `mathjax3_config`\n",
    "\n",
    "The configuration value\n",
    "[mathjax3_config](https://www.sphinx-doc.org/en/master/usage/extensions/math.html#confval-mathjax3_config)\n",
    "can be useful to enable\n",
    "[Automatic Equation Numbering](markdown-cells.ipynb#Automatic-Equation-Numbering).\n",
    "\n",
    "For Sphinx versions below 4.0.0, which used MathJax version 2,\n",
    "the relevant configuration value was called `mathjax_config`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `pygments_style`\n",
    "\n",
    "Use\n",
    "[pygments_style](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-pygments_style)\n",
    "to change the color/font theme that's used for syntax highlighting in source code.\n",
    "\n",
    "This affects both [code cells](code-cells.ipynb)\n",
    "and [code blocks in Markdown cells](markdown-cells.ipynb#Code)\n",
    "(unless overwritten by the\n",
    "[html_theme](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_theme))."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `suppress_warnings`\n",
    "\n",
    "Warnings can be really helpful to detect small mistakes,\n",
    "and you should consider invoking Sphinx with the\n",
    "[-W](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-W)\n",
    "option,\n",
    "which turns warnings into errors.\n",
    "However, warnings can also be annoying,\n",
    "especially if you are fully aware of the \"problem\",\n",
    "but you simply don't care about it for some reason.\n",
    "In this case, you can use\n",
    "[suppress_warnings](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings)\n",
    "to silence specific types of warnings.\n",
    "\n",
    "If you want to suppress all warnings from `nbsphinx`, use this:\n",
    "\n",
    "```python\n",
    "suppress_warnings = [\n",
    "    'nbsphinx',\n",
    "]\n",
    "```\n",
    "\n",
    "You can also be more specific:\n",
    "\n",
    "```python\n",
    "suppress_warnings = [\n",
    "    'nbsphinx.localfile',\n",
    "    'nbsphinx.gallery',\n",
    "    'nbsphinx.thumbnail',\n",
    "    'nbsphinx.notebooktitle',\n",
    "    'nbsphinx.ipywidgets',\n",
    "]\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `nbsphinx` Configuration Values"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_allow_errors`\n",
    "\n",
    "If `True`, the build process is continued even if an exception occurs.\n",
    "\n",
    "See [Ignoring Errors](allow-errors.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_assume_equations`\n",
    "\n",
    "If `False`, do not force loading MathJax on HTML pages generated from notebooks."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_codecell_lexer`\n",
    "\n",
    "Default Pygments lexer for syntax highlighting in code cells.\n",
    "If available,\n",
    "this information is taken from the notebook metadata instead."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_custom_formats`\n",
    "\n",
    "See [Custom Notebook Formats](custom-formats.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_epilog`\n",
    "\n",
    "See [Prolog and Epilog](prolog-and-epilog.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_execute`\n",
    "\n",
    "Whether to execute notebooks before conversion or not.\n",
    "Possible values: `'always'`, `'never'`, `'auto'` (default).\n",
    "\n",
    "See [Explicitly Dis-/Enabling Notebook Execution](never-execute.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_execute_arguments`\n",
    "\n",
    "Kernel arguments used when executing notebooks.\n",
    "\n",
    "See [Configuring the Kernels](configuring-kernels.ipynb#Kernel-Arguments)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_input_prompt`\n",
    "\n",
    "Input prompt for code cells. `%s` is replaced by the execution count.\n",
    "\n",
    "To get a prompt similar to the Classic Notebook, use\n",
    "\n",
    "```python\n",
    "nbsphinx_input_prompt = 'In [%s]:'\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_kernel_name`\n",
    "\n",
    "Use a different kernel than stored in the notebook metadata, e.g.:\n",
    "\n",
    "```python\n",
    "nbsphinx_kernel_name = 'python3'\n",
    "```\n",
    "\n",
    "See [Configuring the Kernels](configuring-kernels.ipynb#Kernel-Name)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_output_prompt`\n",
    "\n",
    "Output prompt for code cells. `%s` is replaced by the execution count.\n",
    "\n",
    "To get a prompt similar to the Classic Notebook, use\n",
    "\n",
    "```python\n",
    "nbsphinx_output_prompt = 'Out[%s]:'\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_prolog`\n",
    "\n",
    "See [Prolog and Epilog](prolog-and-epilog.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_prompt_width`\n",
    "\n",
    "Width of input/output prompts (HTML only).\n",
    "\n",
    "If a prompt is wider than that, it protrudes into the left margin.\n",
    "\n",
    "Any CSS length can be specified."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_requirejs_options`\n",
    "\n",
    "Options for loading RequireJS.\n",
    "See [nbsphinx_requirejs_path](#nbsphinx_requirejs_path)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_requirejs_path`\n",
    "\n",
    "URL or local path to override the default URL\n",
    "for [RequireJS](https://requirejs.org/).\n",
    "\n",
    "If you use a local file,\n",
    "it should be located in a directory listed in\n",
    "[html_static_path](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path).\n",
    "\n",
    "Set to empty string to disable loading RequireJS."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_responsive_width`\n",
    "\n",
    "If the browser window is narrower than this,\n",
    "input/output prompts are on separate lines\n",
    "(HTML only).\n",
    "\n",
    "Any CSS length can be specified."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_thumbnails`\n",
    "\n",
    "A dictionary mapping from a document name\n",
    "(i.e. source file without suffix but with subdirectories)\n",
    "-- optionally containing wildcards --\n",
    "to a thumbnail path to be used in a\n",
    "[thumbnail gallery](subdir/gallery.ipynb). Thumbnails specified\n",
    "in notebooks will override those provided in this dictionary.\n",
    "\n",
    "See [Specifying Thumbnails](gallery/thumbnail-from-conf-py.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_timeout`\n",
    "\n",
    "Controls when a cell will time out.\n",
    "The timeout is given in seconds.\n",
    "Given `-1`, cells will never time out,\n",
    "which is also the default.\n",
    "\n",
    "See [Cell Execution Timeout](timeout.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_widgets_options`\n",
    "\n",
    "Options for loading Jupyter widgets resources.\n",
    "See [nbsphinx_widgets_path](#nbsphinx_widgets_path)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `nbsphinx_widgets_path`\n",
    "\n",
    "URL or local path to override the default URL\n",
    "for Jupyter widgets resources.\n",
    "See [Interactive Widgets (HTML only)](code-cells.ipynb#Interactive-Widgets-(HTML-only)).\n",
    "\n",
    "If you use a local file,\n",
    "it should be located in a directory listed in\n",
    "[html_static_path](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path).\n",
    "\n",
    "For loading the widgets resources,\n",
    "RequireJS is needed,\n",
    "see [nbsphinx_requirejs_path](#nbsphinx_requirejs_path).\n",
    "\n",
    "If `nbsphinx_widgets_path` is not specified,\n",
    "widgets resources are only loaded if at least one notebook\n",
    "actually uses widgets.\n",
    "If you are loading the relevant JavaScript code by some other means already,\n",
    "you can set this option to the empty string to avoid loading it a second time."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}