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

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

# # Usage

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

# ## 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
#     build:
#       os: ubuntu-22.04
#       tools:
#         python: "3"
#     python:
#       install:
#         - requirements: doc/requirements.txt
#     ```
# 
#     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>

# ## Automatic Creation of HTML and PDF output on GitLab Pages
# 
# When using GitLab pages, you can use nbsphinx by adding the file `.gitlab-ci.yml` to your repo and copying the following lines into this file:
# 
# ```yaml
# image: python:3-slim
# 
# variables:
#   PIP: python3 -m pip
#   SPHINX: python3 -m sphinx -W --keep-going --color
# 
# build-docs:
#   stage: build
#   script:
#     - apt-get update -y
#     - apt-get install -y --no-install-recommends pandoc
#     - $PIP install -r doc/requirements.txt
#     - $SPHINX -d doctrees doc html -b html
#     - $SPHINX -d doctrees doc linkcheck -b linkcheck
#   artifacts:
#     when: always
#     paths:
#       - html
#       - linkcheck/output.*
#     
# pages:
#   stage: deploy
#   variables:
#     GIT_STRATEGY: none
#   script:
#     - mv html public
#   artifacts:
#     paths:
#       - public
#   rules:
#     - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
# ```

# ## 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)
# 
# * [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)
# 
# * [python_docs_theme](https://github.com/python/python-docs-theme):
#   [example](https://nbsphinx.readthedocs.io/en/python-docs-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/python-docs-theme^...python-docs-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_immaterial](https://github.com/jbms/sphinx-immaterial):
#   [example](https://nbsphinx.readthedocs.io/en/immaterial-theme/),
#   [usage](https://github.com/spatialaudio/nbsphinx/compare/immaterial-theme^...immaterial-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