#!/usr/bin/env python
# coding: utf-8

# This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/.

# # Usage

# ## Sphinx Setup
# 
# In the directory with your notebook files, run this command (assuming you have [Sphinx](https://www.sphinx-doc.org/) and `nbsphinx` 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.
# 
# 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 make sure that the `extensions` setting
# at least contains `'nbsphinx'`
# (but you might want to add other useful extensions as well):
# 
# ```python
# extensions = [
#     'nbsphinx',
# ]
# ```
# 
# For an example, see this project's  [conf.py](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](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree)
# directive.
# For an example, see this project's `doc/index.rst` file.
# 
# Alternatively, you can delete the file `index.rst`
# and replace it with your own notebook called `index.ipynb`
# which will serve as main page.
# In this case you can create the main [toctree](subdir/toctree.ipynb)
# in `index.ipynb`.

# ### Sphinx Configuration Values
# 
# All configuration values are described in the
# [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/configuration.html),
# 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](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-exclude_patterns).
# For example, you might want to ignore source files in your build directory:
# 
# ```python
# 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](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-extensions),
# otherwise it won't work.
# 
# Other interesting extensions are:
# 
# * `'sphinx.ext.mathjax'` (Sphinx loads this by default)
#   for [math formulas](markdown-cells.ipynb#Equations)
# * `'sphinxcontrib.bibtex'`
#   for [bibliographic references](a-normal-rst-file.rst#references)
# * `'sphinxcontrib.rsvgconverter'`
#   for [SVG->PDF conversion in LaTeX output](markdown-cells.ipynb#SVG-support-for-LaTeX)
# * `'sphinx_copybutton'`
#   for [adding "copy to clipboard" buttons](https://sphinx-copybutton.readthedocs.io/)
#   to all text/code boxes
# * `'sphinx_gallery.load_style'` to load CSS styles for [thumbnail galleries](subdir/gallery.ipynb)

# #### `html_css_files`
# 
# See [Custom CSS](custom-css.ipynb) and
# [html_css_files](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-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](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-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](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sourcelink_suffix) to the empty string:
# 
# ```python
# html_sourcelink_suffix = ''
# ```

# #### `latex_additional_files`
# 
# [latex_additional_files](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-latex_additional_files)
# can be useful if you are using BibTeX files, see
# [References](a-normal-rst-file.rst#references).

# #### `mathjax3_config`
# 
# The configuration value
# [mathjax3_config](https://www.sphinx-doc.org/en/master/usage/extensions/math.html#confval-mathjax3_config)
# can be useful to enable
# [Automatic Equation Numbering](markdown-cells.ipynb#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](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-pygments_style)
# to change the color/font theme that's used for syntax highlighting in source code.
# 
# This affects both [code cells](code-cells.ipynb)
# and [code blocks in Markdown cells](markdown-cells.ipynb#Code)
# (unless overwritten by the
# [html_theme](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_theme)).

# #### `suppress_warnings`
# 
# Warnings can be really helpful to detect small mistakes,
# and you should consider invoking Sphinx with the
# [-W](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-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](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings)
# to silence specific types of warnings.
# 
# If you want to suppress all warnings from `nbsphinx`, use this:
# 
# ```python
# suppress_warnings = [
#     'nbsphinx',
# ]
# ```
# 
# You can also be more specific:
# 
# ```python
# 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](allow-errors.ipynb).

# #### `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](custom-formats.ipynb).

# #### `nbsphinx_epilog`
# 
# See [Prolog and Epilog](prolog-and-epilog.ipynb).

# #### `nbsphinx_execute`
# 
# Whether to execute notebooks before conversion or not.
# Possible values: `'always'`, `'never'`, `'auto'` (default).
# 
# See [Explicitly Dis-/Enabling Notebook Execution](never-execute.ipynb).

# #### `nbsphinx_execute_arguments`
# 
# Kernel arguments used when executing notebooks.
# 
# If you [use Matplotlib for plots](code-cells.ipynb#Plots),
# this setting is recommended:
# 
# ```python
# 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.
# 
# See [Configuring the Kernels](configuring-kernels.ipynb#Kernel-Arguments).

# #### `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
# 
# ```python
# nbsphinx_input_prompt = 'In [%s]:'
# ```

# #### `nbsphinx_kernel_name`
# 
# Use a different kernel than stored in the notebook metadata, e.g.:
# 
# ```python
# nbsphinx_kernel_name = 'python3'
# ```
# 
# See [Configuring the Kernels](configuring-kernels.ipynb#Kernel-Name).

# #### `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
# 
# ```python
# nbsphinx_output_prompt = 'Out[%s]:'
# ```

# #### `nbsphinx_prolog`
# 
# See [Prolog and Epilog](prolog-and-epilog.ipynb).

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

# #### `nbsphinx_requirejs_path`
# 
# URL or local path to override the default URL
# for [RequireJS](https://requirejs.org/).
# 
# If you use a local file,
# it should be located in a directory listed in
# [html_static_path](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-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](subdir/gallery.ipynb).
# 
# See [Specifying Thumbnails](gallery/thumbnail-from-conf-py.ipynb).

# #### `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](timeout.ipynb).

# #### `nbsphinx_widgets_options`
# 
# Options for loading Jupyter widgets resources.
# See [nbsphinx_widgets_path](#nbsphinx_widgets_path).

# #### `nbsphinx_widgets_path`
# 
# URL or local path to override the default URL
# for Jupyter widgets resources.
# See [Interactive Widgets (HTML only)](code-cells.ipynb#Interactive-Widgets-(HTML-only)).
# 
# If you use a local file,
# it should be located in a directory listed in
# [html_static_path](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path).
# 
# For loading the widgets resources,
# RequireJS is needed,
# see [nbsphinx_requirejs_path](#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.

# ## Running Sphinx
# 
# 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:
# 
#     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`.
# 
# 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.
# 
# <div class="alert alert-info">
# 
# 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](executing-notebooks.ipynb).
# 
# </div>
# 
# 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](http://personal.psu.edu/jcc8//software/latexmk-jcc/) (see also [this tutorial](https://mg.readthedocs.io/latexmk.html)).
# 
# 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

# ## Watching for Changes with `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](https://pypi.org/project/sphinx-autobuild)!
# 
# It can be installed with
# 
#     python3 -m pip install sphinx-autobuild
# 
# 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](#Running-Sphinx)).
# Change to the build directory and run
# 
#     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.

# ## Automatic Creation of HTML and PDF output on readthedocs.org
# 
# 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](https://readthedocs.org/dashboard/)
# which of those should be created.
# 
# <div class="alert alert-info">
# 
# Note
# 
# If you want to execute notebooks
# (see [Controlling Notebook Execution](executing-notebooks.ipynb)),
# you'll need to install the appropriate Jupyter kernel.
# In the examples below,
# the IPython kernel is installed from the packet `ipykernel`.
# 
# </div>

# ### Using `requirements.txt`
# 
# 1. Create a file named `.readthedocs.yml`
#     in the main directory of your repository
#     with the following contents:
# 
#     ```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/.
# 
# 1. Create a file named `doc/requirements.txt`
#     (or whatever you chose in the previous step)
#     containing the required `pip` packages:
# 
#     ```
#     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
#     ```

# ### Using `conda`
# 
# 1. Create a file named `.readthedocs.yml`
#     in the main directory of your repository
#     with the following contents:
# 
#     ```yaml
#     version: 2
#     formats: all
#     conda:
#       environment: doc/environment.yml
#     ```
# 
#     For further options see https://docs.readthedocs.io/en/latest/config-file/.
# 
# 1. Create a file named `doc/environment.yml`
#     (or whatever you chose in the previous step)
#     describing a
#     [conda environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)
#     like this:
# 
#     ```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
#     ```
# 
# <div class="alert alert-info">
# 
# Note
# 
# The specification of the `conda-forge` channel is recommended because it tends to have more recent package versions than the default channel.
# 
# </div>

# ## HTML Themes
# 
# The `nbsphinx` extension does *not* provide its own theme, you can use any of the available themes or [create a custom one](https://www.sphinx-doc.org/en/master/development/theming.html#creating-themes), if you feel like it.
# 
# The following (incomplete) list of themes contains up to three links for each theme:
# 
# 1. The documentation (or the official sample page) of this theme (if available; see also the [documentation of the built-in Sphinx themes](https://www.sphinx-doc.org/en/master/usage/theming.html#builtin-themes))
# 1. How the `nbsphinx` documentation looks when using this theme
# 1. How to enable this theme using either `requirements.txt` or `readthedocs.yml` and theme-specific settings (in some cases)
# 
# ### Sphinx's Built-In Themes
# 
# * `agogo`:
#   [example](https://nbsphinx.readthedocs.io/en/agogo-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/agogo-theme^...agogo-theme)
# 
# * [alabaster](https://alabaster.readthedocs.io/):
#   [example](https://nbsphinx.readthedocs.io/en/alabaster-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/alabaster-theme^...alabaster-theme)
# 
# * `bizstyle`:
#   [example](https://nbsphinx.readthedocs.io/en/bizstyle-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/bizstyle-theme^...bizstyle-theme)
# 
# * `classic`:
#   [example](https://nbsphinx.readthedocs.io/en/classic-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/classic-theme^...classic-theme)
# 
# * `haiku`:
#   [example](https://nbsphinx.readthedocs.io/en/haiku-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/haiku-theme^...haiku-theme)
# 
# * `nature`:
#   [example](https://nbsphinx.readthedocs.io/en/nature-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/nature-theme^...nature-theme)
# 
# * `pyramid`:
#   [example](https://nbsphinx.readthedocs.io/en/pyramid-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/pyramid-theme^...pyramid-theme)
# 
# * `scrolls`:
#   [example](https://nbsphinx.readthedocs.io/en/scrolls-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/scrolls-theme^...scrolls-theme)
# 
# * `sphinxdoc`:
#   [example](https://nbsphinx.readthedocs.io/en/sphinxdoc-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/sphinxdoc-theme^...sphinxdoc-theme)
# 
# * `traditional`:
#   [example](https://nbsphinx.readthedocs.io/en/traditional-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/traditional-theme^...traditional-theme)
# 
# ### 3rd-Party Themes
# 
# * [basicstrap](https://pythonhosted.org/sphinxjp.themes.basicstrap/):
#   [example](https://nbsphinx.readthedocs.io/en/basicstrap-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/basicstrap-theme^...basicstrap-theme)
# 
# * [better](https://sphinx-better-theme.readthedocs.io/):
#   [example](https://nbsphinx.readthedocs.io/en/better-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/better-theme^...better-theme)
# 
# * [bootstrap](https://sphinx-bootstrap-theme.readthedocs.io/):
#   [example](https://nbsphinx.readthedocs.io/en/bootstrap-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/bootstrap-theme^...bootstrap-theme)
# 
# * [bootstrap-astropy](https://github.com/astropy/astropy-sphinx-theme):
#   [example](https://nbsphinx.readthedocs.io/en/astropy-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/astropy-theme^...astropy-theme)
# 
# * [cloud/redcloud/greencloud](https://cloud-sptheme.readthedocs.io/):
#   [example](https://nbsphinx.readthedocs.io/en/cloud-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/cloud-theme^...cloud-theme)
# 
# * [dask_sphinx_theme](https://github.com/dask/dask-sphinx-theme):
#   [example](https://nbsphinx.readthedocs.io/en/dask-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/dask-theme^...dask-theme)
# 
# * [furo](https://github.com/pradyunsg/furo):
#   [example](https://nbsphinx.readthedocs.io/en/furo-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/furo-theme^...furo-theme)
# 
# * [guzzle_sphinx_theme](https://github.com/guzzle/guzzle_sphinx_theme):
#   [example](https://nbsphinx.readthedocs.io/en/guzzle-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/guzzle-theme^...guzzle-theme)
# 
# * [insipid](https://github.com/mgeier/insipid-sphinx-theme/):
#   [example](https://nbsphinx.readthedocs.io/en/insipid-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/insipid-theme^...insipid-theme)
# 
# * [jupyter](https://github.com/jupyter/jupyter-sphinx-theme/):
#   [example](https://nbsphinx.readthedocs.io/en/jupyter-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/jupyter-theme^...jupyter-theme)
# 
# * [maisie_sphinx_theme](https://github.com/maisie-dev/maisie-sphinx-theme):
#   [example](https://nbsphinx.readthedocs.io/en/maisie-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/maisie-theme^...maisie-theme)
# 
# * [pangeo](https://github.com/pangeo-data/sphinx_pangeo_theme/):
#   [example](https://nbsphinx.readthedocs.io/en/pangeo-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/pangeo-theme^...pangeo-theme)
# 
# * [pydata_sphinx_theme](https://pydata-sphinx-theme.readthedocs.io/):
#   [example](https://nbsphinx.readthedocs.io/en/pydata-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/pydata-theme^...pydata-theme)
# 
# * [pytorch_sphinx_theme](https://github.com/shiftlab/pytorch_sphinx_theme):
#   [example](https://nbsphinx.readthedocs.io/en/pytorch-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/pytorch-theme^...pytorch-theme)
# 
# * [sizzle](https://docs.red-dove.com/sphinx_sizzle_theme/):
#   [example](https://nbsphinx.readthedocs.io/en/sizzle-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/sizzle-theme^...sizzle-theme)
# 
# * [sphinx_book_theme](https://sphinx-book-theme.readthedocs.io/):
#   [example](https://nbsphinx.readthedocs.io/en/sphinx-book-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/sphinx-book-theme^...sphinx-book-theme)
# 
# * [sphinx_holoviz_theme](https://github.com/pyviz-dev/sphinx_holoviz_theme):
#   [example](https://nbsphinx.readthedocs.io/en/holoviz-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/holoviz-theme^...holoviz-theme)
# 
# * [sphinx_material](https://github.com/bashtage/sphinx-material):
#   [example](https://nbsphinx.readthedocs.io/en/material-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/material-theme^...material-theme)
# 
# * [sphinx_py3doc_enhanced_theme](https://github.com/ionelmc/sphinx-py3doc-enhanced-theme):
#   [example](https://nbsphinx.readthedocs.io/en/py3doc-enhanced-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/py3doc-enhanced-theme^...py3doc-enhanced-theme)
# 
# * [sphinx_rtd_theme](https://github.com/readthedocs/sphinx_rtd_theme):
#   [example](https://nbsphinx.readthedocs.io/en/rtd-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/rtd-theme^...rtd-theme)
# 
# * [typlog](https://github.com/typlog/sphinx-typlog-theme):
#   [example](https://nbsphinx.readthedocs.io/en/typlog-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/typlog-theme^...typlog-theme)
# 
# If you know of another Sphinx theme that should be included here, please open an [issue on Github](https://github.com/spatialaudio/nbsphinx/issues).
# An overview of many more themes can be found at https://sphinx-themes.org/.

# ## Using Notebooks with Git
# 
# [Git](https://git-scm.com/) 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](pre-executed.ipynb)).
# 
# 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](executing-notebooks.ipynb) 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://web.archive.org/web/20191003081426/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/
# * https://github.com/ResearchSoftwareActions/EnsureCleanNotebooksAction