doc/usage.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": [
    "# Usage"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sphinx Setup\n",
    "\n",
    "In the directory with your notebook files, run this command (assuming you have [Sphinx](https://www.sphinx-doc.org/) and `nbsphinx` installed already):\n",
    "\n",
    "    python3 -m sphinx.cmd.quickstart\n",
    "\n",
    "Answer the questions that appear on the screen. In case of doubt, just press the `<Return>` key repeatedly to take the default values.\n",
    "\n",
    "After that, there will be a few brand-new files in the current directory.\n",
    "You'll have to make a few changes to the file named `conf.py`.\n",
    "You should make sure that the `extensions` setting\n",
    "at least contains `'nbsphinx'`\n",
    "(but you might want to add other useful extensions as well):\n",
    "\n",
    "```python\n",
    "extensions = [\n",
    "    'nbsphinx',\n",
    "]\n",
    "```\n",
    "\n",
    "For an example, see this project's  [conf.py](conf.py) file.\n",
    "\n",
    "Once your `conf.py` is in place,\n",
    "edit the file named `index.rst` and add the file names of your notebooks\n",
    "(without the `.ipynb` extension)\n",
    "to the\n",
    "[toctree](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree)\n",
    "directive.\n",
    "For an example, see this project's `doc/index.rst` file.\n",
    "\n",
    "Alternatively, you can delete the file `index.rst`\n",
    "and replace it with your own notebook called `index.ipynb`\n",
    "which will serve as main page.\n",
    "In this case you can create the main [toctree](subdir/toctree.ipynb)\n",
    "in `index.ipynb`."
   ]
  },
  {
   "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\n",
    "* `'sphinx_gallery.load_style'` to load CSS styles for [thumbnail galleries](subdir/gallery.ipynb)"
   ]
  },
  {
   "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).\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."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Running Sphinx\n",
    "\n",
    "To create the HTML pages, use this command:\n",
    "\n",
    "    python3 -m sphinx <source-dir> <build-dir>\n",
    "\n",
    "If you have many notebooks, you can do a parallel build by using the `-j` option:\n",
    "\n",
    "    python3 -m sphinx <source-dir> <build-dir> -j<number-of-processes>\n",
    "\n",
    "For example, if your source files are in the current directory and you have 4 CPU cores, you can run this:\n",
    "\n",
    "    python3 -m sphinx . _build -j4\n",
    "\n",
    "Afterwards, you can find the main HTML file in `_build/index.html`.\n",
    "\n",
    "Subsequent builds will be faster, because only those source files which have changed will be re-built.\n",
    "To force re-building all source files, use the `-E` option.\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "Note\n",
    "\n",
    "By default, notebooks will be executed during the Sphinx build process only if they do not have any output cells stored.\n",
    "See [Controlling Notebook Execution](executing-notebooks.ipynb).\n",
    "\n",
    "</div>\n",
    "\n",
    "To create LaTeX output, use:\n",
    "\n",
    "    python3 -m sphinx <source-dir> <build-dir> -b latex\n",
    "\n",
    "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)).\n",
    "\n",
    "Sphinx can automatically check if the links you are using are still valid.\n",
    "Just invoke it like this:\n",
    "\n",
    "    python3 -m sphinx <source-dir> <build-dir> -b linkcheck"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Watching for Changes with `sphinx-autobuild`\n",
    "\n",
    "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)!\n",
    "\n",
    "It can be installed with\n",
    "\n",
    "    python3 -m pip install sphinx-autobuild\n",
    "\n",
    "You can start auto-building your files with\n",
    "\n",
    "    python3 -m sphinx_autobuild <source-dir> <build-dir>\n",
    "\n",
    "This will start a local webserver which will serve the generated HTML pages at http://localhost:8000/.\n",
    "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.\n",
    "Neat!\n",
    "\n",
    "You can also abuse this to auto-build the LaTeX output:\n",
    "\n",
    "    python3 -m sphinx_autobuild <source-dir> <build-dir> -b latex\n",
    "\n",
    "However, to auto-build the final PDF file as well, you'll need an additional tool.\n",
    "Again, you can use `latexmk` for this (see [above](#Running-Sphinx)).\n",
    "Change to the build directory and run\n",
    "\n",
    "    latexmk -pdf -pvc\n",
    "\n",
    "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."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Automatic Creation of HTML and PDF output on readthedocs.org\n",
    "\n",
    "There are two different methods, both of which are described below.\n",
    "\n",
    "In both cases, you'll first have to create an account on https://readthedocs.org/\n",
    "and connect your GitLab/Github/Bitbucket/... account.\n",
    "Instead of connecting, you can also manually add\n",
    "any publicly available Git/Subversion/Mercurial/Bazaar/... repository.\n",
    "\n",
    "After doing the steps described below,\n",
    "you only have to \"push\" to your repository,\n",
    "and the HTML pages and the PDF file of your stuff\n",
    "are automagically created on readthedocs.org.\n",
    "Awesome!\n",
    "\n",
    "You can even have different versions of your stuff,\n",
    "just use Git tags and branches and select in the\n",
    "[readthedocs.org settings](https://readthedocs.org/dashboard/)\n",
    "which of those should be created.\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "Note\n",
    "\n",
    "If you want to execute notebooks\n",
    "(see [Controlling Notebook Execution](executing-notebooks.ipynb)),\n",
    "you'll need to install the appropriate Jupyter kernel.\n",
    "In the examples below,\n",
    "the IPython kernel is installed from the packet `ipykernel`.\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using `requirements.txt`\n",
    "\n",
    "1. Create a file named `.readthedocs.yml`\n",
    "    in the main directory of your repository\n",
    "    with the following contents:\n",
    "\n",
    "    ```yaml\n",
    "    version: 2\n",
    "    formats: all\n",
    "    python:\n",
    "      version: 3\n",
    "      install:\n",
    "        - requirements: doc/requirements.txt\n",
    "      system_packages: true\n",
    "    ```\n",
    "\n",
    "    For further options see https://docs.readthedocs.io/en/latest/config-file/.\n",
    "\n",
    "1. Create a file named `doc/requirements.txt`\n",
    "    (or whatever you chose in the previous step)\n",
    "    containing the required `pip` packages:\n",
    "\n",
    "    ```\n",
    "    ipykernel\n",
    "    nbsphinx\n",
    "    ```\n",
    "\n",
    "    You can also install directly from Github et al., using a specific branch/tag/commit, e.g.\n",
    "\n",
    "    ```\n",
    "    git+https://github.com/spatialaudio/nbsphinx.git@master\n",
    "    ```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using `conda`\n",
    "\n",
    "1. Create a file named `.readthedocs.yml`\n",
    "    in the main directory of your repository\n",
    "    with the following contents:\n",
    "\n",
    "    ```yaml\n",
    "    version: 2\n",
    "    formats: all\n",
    "    conda:\n",
    "      environment: doc/environment.yml\n",
    "    ```\n",
    "\n",
    "    For further options see https://docs.readthedocs.io/en/latest/config-file/.\n",
    "\n",
    "1. Create a file named `doc/environment.yml`\n",
    "    (or whatever you chose in the previous step)\n",
    "    describing a\n",
    "    [conda environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)\n",
    "    like this:\n",
    "\n",
    "    ```yaml\n",
    "    channels:\n",
    "      - conda-forge\n",
    "    dependencies:\n",
    "      - python>=3\n",
    "      - pandoc\n",
    "      - ipykernel\n",
    "      - pip\n",
    "      - pip:\n",
    "        - nbsphinx\n",
    "    ```\n",
    "\n",
    "    It is up to you if you want to install `nbsphinx` with `conda` or with `pip`\n",
    "    (but note that the `conda` package might be outdated).\n",
    "    And you can of course add further `conda` and `pip` packages.\n",
    "    You can also install packages directly from Github et al.,\n",
    "    using a specific branch/tag/commit, e.g.\n",
    "\n",
    "    ```yaml\n",
    "      - pip:\n",
    "        - git+https://github.com/spatialaudio/nbsphinx.git@master\n",
    "    ```\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "Note\n",
    "\n",
    "The specification of the `conda-forge` channel is recommended because it tends to have more recent package versions than the default channel.\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Automatic Creation of HTML and PDF output on GitLab Pages\n",
    "\n",
    "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:\n",
    "```\n",
    "image: python:3-slim\n",
    "\n",
    "variables:\n",
    "  PIP: python3 -m pip\n",
    "  SPHINX: python3 -m sphinx -W --keep-going --color\n",
    "\n",
    "build-docs:\n",
    "  stage: build\n",
    "  script:\n",
    "    - apt-get update -y\n",
    "    - apt-get install -y --no-install-recommends pandoc\n",
    "    - $PIP install -r doc/requirements.txt\n",
    "    - $SPHINX -d doctrees doc html -b html\n",
    "    - $SPHINX -d doctrees doc linkcheck -b linkcheck\n",
    "  artifacts:\n",
    "    when: always\n",
    "    paths:\n",
    "      - html\n",
    "      - linkcheck/output.*\n",
    "    \n",
    "pages:\n",
    "  stage: deploy\n",
    "  variables:\n",
    "    GIT_STRATEGY: none\n",
    "  script:\n",
    "    - mv html public\n",
    "  artifacts:\n",
    "    paths:\n",
    "      - public\n",
    "  rules:\n",
    "    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH\n",
    "```\n",
    "Note:  \n",
    "\n",
    "You might have to change the line `docs/` to `docs/source` in case that you have this folder structure, which is the default when using `sphinx-quickstart`. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## HTML Themes\n",
    "\n",
    "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.\n",
    "\n",
    "The following (incomplete) list of themes contains up to three links for each theme:\n",
    "\n",
    "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))\n",
    "1. How the `nbsphinx` documentation looks when using this theme\n",
    "1. How to enable this theme using either `requirements.txt` or `readthedocs.yml` and theme-specific settings (in some cases)\n",
    "\n",
    "### Sphinx's Built-In Themes\n",
    "\n",
    "* `agogo`:\n",
    "  [example](https://nbsphinx.readthedocs.io/en/agogo-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/agogo-theme^...agogo-theme)\n",
    "\n",
    "* [alabaster](https://alabaster.readthedocs.io/):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/alabaster-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/alabaster-theme^...alabaster-theme)\n",
    "\n",
    "* `bizstyle`:\n",
    "  [example](https://nbsphinx.readthedocs.io/en/bizstyle-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/bizstyle-theme^...bizstyle-theme)\n",
    "\n",
    "* `classic`:\n",
    "  [example](https://nbsphinx.readthedocs.io/en/classic-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/classic-theme^...classic-theme)\n",
    "\n",
    "* `haiku`:\n",
    "  [example](https://nbsphinx.readthedocs.io/en/haiku-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/haiku-theme^...haiku-theme)\n",
    "\n",
    "* `nature`:\n",
    "  [example](https://nbsphinx.readthedocs.io/en/nature-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/nature-theme^...nature-theme)\n",
    "\n",
    "* `pyramid`:\n",
    "  [example](https://nbsphinx.readthedocs.io/en/pyramid-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/pyramid-theme^...pyramid-theme)\n",
    "\n",
    "* `scrolls`:\n",
    "  [example](https://nbsphinx.readthedocs.io/en/scrolls-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/scrolls-theme^...scrolls-theme)\n",
    "\n",
    "* `sphinxdoc`:\n",
    "  [example](https://nbsphinx.readthedocs.io/en/sphinxdoc-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/sphinxdoc-theme^...sphinxdoc-theme)\n",
    "\n",
    "* `traditional`:\n",
    "  [example](https://nbsphinx.readthedocs.io/en/traditional-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/traditional-theme^...traditional-theme)\n",
    "\n",
    "### 3rd-Party Themes\n",
    "\n",
    "* [basicstrap](https://pythonhosted.org/sphinxjp.themes.basicstrap/):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/basicstrap-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/basicstrap-theme^...basicstrap-theme)\n",
    "\n",
    "* [better](https://sphinx-better-theme.readthedocs.io/):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/better-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/better-theme^...better-theme)\n",
    "\n",
    "* [bootstrap](https://sphinx-bootstrap-theme.readthedocs.io/):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/bootstrap-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/bootstrap-theme^...bootstrap-theme)\n",
    "\n",
    "* [bootstrap-astropy](https://github.com/astropy/astropy-sphinx-theme):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/astropy-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/astropy-theme^...astropy-theme)\n",
    "\n",
    "* [cloud/redcloud/greencloud](https://cloud-sptheme.readthedocs.io/):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/cloud-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/cloud-theme^...cloud-theme)\n",
    "\n",
    "* [dask_sphinx_theme](https://github.com/dask/dask-sphinx-theme):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/dask-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/dask-theme^...dask-theme)\n",
    "\n",
    "* [furo](https://github.com/pradyunsg/furo):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/furo-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/furo-theme^...furo-theme)\n",
    "\n",
    "* [guzzle_sphinx_theme](https://github.com/guzzle/guzzle_sphinx_theme):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/guzzle-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/guzzle-theme^...guzzle-theme)\n",
    "\n",
    "* [insipid](https://github.com/mgeier/insipid-sphinx-theme/):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/insipid-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/insipid-theme^...insipid-theme)\n",
    "\n",
    "* [maisie_sphinx_theme](https://github.com/maisie-dev/maisie-sphinx-theme):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/maisie-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/maisie-theme^...maisie-theme)\n",
    "\n",
    "* [pangeo](https://github.com/pangeo-data/sphinx_pangeo_theme/):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/pangeo-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/pangeo-theme^...pangeo-theme)\n",
    "\n",
    "* [pydata_sphinx_theme](https://pydata-sphinx-theme.readthedocs.io/):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/pydata-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/pydata-theme^...pydata-theme)\n",
    "\n",
    "* [python_docs_theme](https://github.com/python/python-docs-theme):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/python-docs-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/python-docs-theme^...python-docs-theme)\n",
    "\n",
    "* [pytorch_sphinx_theme](https://github.com/shiftlab/pytorch_sphinx_theme):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/pytorch-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/pytorch-theme^...pytorch-theme)\n",
    "\n",
    "* [sizzle](https://docs.red-dove.com/sphinx_sizzle_theme/):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/sizzle-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/sizzle-theme^...sizzle-theme)\n",
    "\n",
    "* [sphinx_book_theme](https://sphinx-book-theme.readthedocs.io/):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/sphinx-book-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/sphinx-book-theme^...sphinx-book-theme)\n",
    "\n",
    "* [sphinx_holoviz_theme](https://github.com/pyviz-dev/sphinx_holoviz_theme):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/holoviz-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/holoviz-theme^...holoviz-theme)\n",
    "\n",
    "* [sphinx_material](https://github.com/bashtage/sphinx-material):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/material-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/material-theme^...material-theme)\n",
    "\n",
    "* [sphinx_py3doc_enhanced_theme](https://github.com/ionelmc/sphinx-py3doc-enhanced-theme):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/py3doc-enhanced-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/py3doc-enhanced-theme^...py3doc-enhanced-theme)\n",
    "\n",
    "* [sphinx_rtd_theme](https://github.com/readthedocs/sphinx_rtd_theme):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/rtd-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/rtd-theme^...rtd-theme)\n",
    "\n",
    "* [typlog](https://github.com/typlog/sphinx-typlog-theme):\n",
    "  [example](https://nbsphinx.readthedocs.io/en/typlog-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/typlog-theme^...typlog-theme)\n",
    "\n",
    "If you know of another Sphinx theme that should be included here, please open an [issue on Github](https://github.com/spatialaudio/nbsphinx/issues).\n",
    "An overview of many more themes can be found at https://sphinx-themes.org/."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using Notebooks with Git\n",
    "\n",
    "[Git](https://git-scm.com/) is extremely useful for managing source code and it can and should also be used for managing Jupyter notebooks.\n",
    "There is one caveat, however:\n",
    "Notebooks can contain output cells with rich media like images, plots, sounds, HTML, JavaScript and many other types of bulky machine-created content.\n",
    "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.\n",
    "Working with multiple collaborators on a notebook can become very tedious because of this.\n",
    "\n",
    "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)).\n",
    "\n",
    "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.\n",
    "See [Controlling Notebook Execution](executing-notebooks.ipynb) for how this behavior can be customized.\n",
    "\n",
    "In the Jupyter Notebook application, you can manually clear all outputs by selecting\n",
    "\"Cell\" $\\to$ \"All Output\" $\\to$ \"Clear\" from the menu.\n",
    "In JupyterLab, the menu items are \"Edit\" $\\to$ \"Clear All Outputs\".\n",
    "\n",
    "There are several tools available to remove outputs from multiple files at once without having to open them separately.\n",
    "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.\n",
    "For details, have a look at those links:\n",
    "\n",
    "* https://github.com/kynan/nbstripout\n",
    "* https://github.com/toobaz/ipynb_output_filter\n",
    "* https://tillahoffmann.github.io/2017/04/17/versioning-jupyter-notebooks-with-git.html\n",
    "* http://timstaley.co.uk/posts/making-git-and-jupyter-notebooks-play-nice/\n",
    "* https://web.archive.org/web/20191003081426/https://pascalbugnion.net/blog/ipython-notebooks-and-git.html\n",
    "* https://github.com/choldgraf/nbclean\n",
    "* https://jamesfolberth.org/articles/2017/08/07/git-commit-hook-for-jupyter-notebooks/\n",
    "* https://github.com/ResearchSoftwareActions/EnsureCleanNotebooksAction"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.9.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}