{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": "hidden"
   },
   "source": [
    "This notebook is part of the `nbsphinx` documentation: http://nbsphinx.readthedocs.io/."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Usage\n",
    "\n",
    "## Installation\n",
    "\n",
    "### nbsphinx\n",
    "\n",
    "Install `nbsphinx` with `pip`:\n",
    "\n",
    "    python3 -m pip install nbsphinx --user\n",
    "\n",
    "If you want to install it system-wide for all users (assuming you have the necessary rights), just drop the `--user` flag.\n",
    "\n",
    "If you suddenly change your mind, you can un-install it with:\n",
    "\n",
    "    python3 -m pip uninstall nbsphinx\n",
    "\n",
    "Depending on your Python installation, you may have to use `python` instead of `python3`.\n",
    "Recent versions of Python already come with `pip` pre-installed.\n",
    "If you don't have it, you can [install it manually](https://pip.pypa.io/en/latest/installing/).\n",
    "\n",
    "To upgrade to the newest release, use the `--upgrade` flag:\n",
    "\n",
    "    python3 -m pip install nbsphinx --upgrade --user\n",
    "\n",
    "If you don't want to use `pip`, you can also try to install `nbsphinx` with your package manager.\n",
    "For example, there is a [package for conda-forge](https://anaconda.org/conda-forge/nbsphinx)\n",
    "and packages for\n",
    "[Debian](https://packages.debian.org/search?keywords=nbsphinx),\n",
    "[Ubuntu](http://packages.ubuntu.com/search?keywords=nbsphinx), [Arch](https://aur.archlinux.org/packages/python-nbsphinx/)\n",
    "and [Gentoo](https://packages.gentoo.org/packages/dev-python/nbsphinx) Linux.\n",
    "Note that those might not provide the latest releases.\n",
    "\n",
    "### pandoc\n",
    "\n",
    "The stand-alone program [pandoc](http://pandoc.org/) is used to convert Markdown content to something Sphinx can understand. You have to install this program separately, ideally with your package manager. If you are using `conda`, you can select the [conda-forge](https://conda-forge.github.io/) channel to install the [pandoc](https://anaconda.org/conda-forge/pandoc) package.\n",
    "If that doesn't work out for you, have a look at `pandoc`'s [installation instructions](http://pandoc.org/installing.html).\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "**Note:**\n",
    "\n",
    "The use of `pandoc` in `nbsphinx` is temporary, but will likely stay that way for a long time, see [issue #36](https://github.com/spatialaudio/nbsphinx/issues/36).\n",
    "\n",
    "</div>\n",
    "\n",
    "### Syntax Highlighting\n",
    "\n",
    "To get proper syntax highlighting in code cells, you'll need an appropriate *Pygments lexer*.\n",
    "This of course depends on the programming language of your Jupyter notebooks (more specifically, the `pygments_lexer` metadata of your notebooks).\n",
    "\n",
    "For example, if you use Python in your notebooks, you'll have to have the `IPython` package installed:\n",
    "\n",
    "    python3 -m pip install IPython --user\n",
    "\n",
    "You'll most likely have this installed already.\n",
    "\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "**Note:**\n",
    "\n",
    "If you are using Anaconda and syntax highlighting in code cells doesn't seem to work,\n",
    "you can try to install IPython with `pip`, or as a work-around,\n",
    "add `'IPython.sphinxext.ipython_console_highlighting'` to `extensions` in my `conf.py`.\n",
    "\n",
    "For details, see [Anaconda issue #1430](https://github.com/ContinuumIO/anaconda-issues/issues/1430) and\n",
    "[nbsphinx issue #24](https://github.com/spatialaudio/nbsphinx/issues/24).\n",
    "\n",
    "</div>\n",
    "\n",
    "### Jupyter Kernel\n",
    "\n",
    "If you want to execute your notebooks during the Sphinx build process (see [Executing Notebooks](executing-notebooks.ipynb)), you need an appropriate [Jupyter kernel](http://jupyter.readthedocs.io/en/latest/projects/kernels.html) installed.\n",
    "\n",
    "For example, if you use Python, you should install the `ipykernel` package:\n",
    "\n",
    "    python3 -m pip install ipykernel --user\n",
    "\n",
    "Again, it's very likely that you have that installed already."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sphinx Setup\n",
    "\n",
    "In the directory with your notebook files, run this command (assuming you have [Sphinx](http://sphinx-doc.org/) installed already):\n",
    "\n",
    "    python3 -m sphinx.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](conf.py). You should at least check if those two variables contain the right things:\n",
    "\n",
    "```python\n",
    "extensions = [\n",
    "    'nbsphinx',\n",
    "    'sphinx.ext.mathjax',\n",
    "]\n",
    "exclude_patterns = ['_build', '**.ipynb_checkpoints']\n",
    "```\n",
    "\n",
    "Once your `conf.py` is in place, edit the file named `index.rst` and add the file names of your notebooks (with or without the `.ipynb` extension) to the [toctree](http://www.sphinx-doc.org/en/stable/markup/toctree.html) directive.\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "**autosummary bug:**\n",
    "\n",
    "If you are using the `sphinx.ext.autosummary` Sphinx extension, there is [a bug in Sphinx (below version 1.5)](https://github.com/sphinx-doc/sphinx/issues/2485) which prevents notebooks from being parsed. \n",
    "As a work-around you can explicitly list all the files for which autosummary should be ran using the  [autosummary_generate](http://www.sphinx-doc.org/en/stable/ext/autosummary.html#confval-autosummary_generate) variable in `conf.py`.  For example,\n",
    "\n",
    "```python\n",
    "autosummary_generate = ['myfile1.rst', 'myfile2.rst']\n",
    "```\n",
    "\n",
    "</div>"
   ]
  },
  {
   "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",
    "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://users.phys.psu.edu/~collins/software/latexmk-jcc/) (see also [this tutorial](http://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.python.org/pypi/sphinx-autobuild)!\n",
    "\n",
    "It can be installed with\n",
    "\n",
    "    python3 -m pip install sphinx-autobuild --user\n",
    "\n",
    "You can start auto-building your files with\n",
    "\n",
    "    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",
    "    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](https://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/ and connect your Github/Bitbucket account. Instead of connecting, you can also manually add any publicly available Git/Subversion/Mercurial/Bazaar repository.\n",
    "\n",
    "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!\n",
    "\n",
    "You can even have different versions of your stuff, just use Git tags and branches and select in the readthedocs.org settings (under \"Admin\", \"Versions\") which of those should be created.\n",
    "\n",
    "If your new versions are not automatically built, go to the “Settings” of your Github repository, continue to “Integrations & services”, and make sure that “ReadTheDocs” is listed and activated in the “Services” section. If not, use “Add service”. There is probably a similar thing for Bitbucket and others.\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "**Note:**\n",
    "\n",
    "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 ist installed from the packet `ipykernel`.\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using `requirements.txt`\n",
    "\n",
    "1. Create a file named `requirements.txt` (or whatever name you wish) in your repository containing the required pip packages:\n",
    "\n",
    "        sphinx>=1.4\n",
    "        ipykernel\n",
    "        nbsphinx\n",
    "        \n",
    "    You can also install directly from Github et al., using a specific branch/tag/commit, e.g.\n",
    "\n",
    "        git+https://github.com/spatialaudio/nbsphinx.git@master\n",
    "\n",
    "1. In the \"Advanced Settings\" on readthedocs.org, specify the path to your `requirements.txt` file (or however you called it) in the box labeled \"Requirements file\". Kinda obvious, isn't it?\n",
    "\n",
    "1. Still in the \"Advanced Settings\", make sure the right Python interpreter is chosen.  This must be the same version (2.x or 3.x) as you were using in your notebooks!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using `conda`\n",
    "\n",
    "1. Create a file named `readthedocs.yml` in the main directory of your repository, containing the name of yet another file:\n",
    "\n",
    "        conda:\n",
    "          file: readthedocs-environment.yml\n",
    "\n",
    "1. Create the file mentioned above.\n",
    "You can choose whatever name you want (it may also live in a subdirectory, e.g. `doc/environment.yml`), it just has to match whatever is specified in `readthedocs.yml`.\n",
    "The second file describes a [conda environment](http://conda.pydata.org/docs/using/envs.html) and should contain something like this:\n",
    "\n",
    "        channels:\n",
    "          - conda-forge\n",
    "        dependencies:\n",
    "          - python==3.5\n",
    "          - sphinx>=1.4\n",
    "          - pandoc\n",
    "          - nbconvert\n",
    "          - ipykernel\n",
    "          - pip:\n",
    "            - nbsphinx\n",
    "\n",
    "    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.\n",
    "    \n",
    "          - pip:\n",
    "            - git+https://github.com/spatialaudio/nbsphinx.git@master\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "**Note:**\n",
    "\n",
    "The specification of the `conda-forge` channel is necessary for the `pandoc` package, which is not part of the default channel.\n",
    "\n",
    "</div>\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "**Note:**\n",
    "\n",
    "Most of the \"Advanced Settings\" on readthedocs.org will be ignored if you have a `readthedocs.yml` file.\n",
    "\n",
    "</div>\n",
    "\n",
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "**Warning:**\n",
    "\n",
    "If you have a very long repository name (or branch name), you might run into this quite obscure problem: ['placeholder too short'](https://github.com/rtfd/readthedocs.org/issues/1902).\n",
    "\n",
    "</div>"
   ]
  },
  {
   "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](http://www.sphinx-doc.org/en/stable/theming.html#creating-themes), if you feel like it.\n",
    "\n",
    "The following (incomplete) list of themes contains several 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](http://www.sphinx-doc.org/en/latest/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",
    "* [alabaster](https://alabaster.readthedocs.io/):\n",
    "  [example](http://nbsphinx.readthedocs.io/en/alabaster-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/alabaster-theme^...alabaster-theme)\n",
    "\n",
    "* `pyramid`:\n",
    "  [example](http://nbsphinx.readthedocs.io/en/pyramid-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/pyramid-theme^...pyramid-theme)\n",
    "\n",
    "* `classic`:\n",
    "  [example](http://nbsphinx.readthedocs.io/en/classic-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/classic-theme^...classic-theme)\n",
    "\n",
    "* `bizstyle`:\n",
    "  [example](http://nbsphinx.readthedocs.io/en/bizstyle-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/bizstyle-theme^...bizstyle-theme)\n",
    "\n",
    "* `haiku`:\n",
    "  [example](http://nbsphinx.readthedocs.io/en/haiku-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/haiku-theme^...haiku-theme)\n",
    "\n",
    "* `traditional`:\n",
    "  [example](http://nbsphinx.readthedocs.io/en/traditional-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/traditional-theme^...traditional-theme)\n",
    "\n",
    "* `agogo`:\n",
    "  [example](http://nbsphinx.readthedocs.io/en/agogo-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/agogo-theme^...agogo-theme)\n",
    "\n",
    "* `nature`:\n",
    "  [example](http://nbsphinx.readthedocs.io/en/nature-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/nature-theme^...nature-theme)\n",
    "\n",
    "### 3rd-Party Themes\n",
    "\n",
    "* [sphinx_rtd_theme](https://github.com/snide/sphinx_rtd_theme):\n",
    "  [example](http://nbsphinx.readthedocs.io/en/rtd-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/rtd-theme^...rtd-theme)\n",
    "\n",
    "* [bootstrap](http://sphinx-bootstrap-theme.readthedocs.io/):\n",
    "  [example](http://nbsphinx.readthedocs.io/en/bootstrap-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/bootstrap-theme^...bootstrap-theme)\n",
    "\n",
    "* [cloud](https://pythonhosted.org/cloud_sptheme/):\n",
    "  [example](http://nbsphinx.readthedocs.io/en/cloud-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/cloud-theme^...cloud-theme)\n",
    "\n",
    "* [sphinx_py3doc_enhanced_theme](https://github.com/ionelmc/sphinx-py3doc-enhanced-theme):\n",
    "  [example](http://nbsphinx.readthedocs.io/en/py3doc-enh-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/py3doc-enh-theme^...py3doc-enh-theme)\n",
    "\n",
    "* [basicstrap](http://pythonhosted.org/sphinxjp.themes.basicstrap/):\n",
    "  [example](http://nbsphinx.readthedocs.io/en/basicstrap-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/basicstrap-theme^...basicstrap-theme)\n",
    "\n",
    "* [dotted](https://pythonhosted.org/sphinxjp.themes.dotted/):\n",
    "  [example](http://nbsphinx.readthedocs.io/en/dotted-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/dotted-theme^...dotted-theme)\n",
    "\n",
    "* [better](https://sphinx-better-theme.readthedocs.io/):\n",
    "  [example](http://nbsphinx.readthedocs.io/en/better-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/better-theme^...better-theme)\n",
    "\n",
    "* [guzzle_sphinx_theme](https://github.com/guzzle/guzzle_sphinx_theme):\n",
    "  [example](http://nbsphinx.readthedocs.io/en/guzzle-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/guzzle-theme^...guzzle-theme)\n",
    "\n",
    "* [julia](https://github.com/JuliaLang/JuliaDoc):\n",
    "  [example](http://nbsphinx.readthedocs.io/en/julia-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/julia-theme^...julia-theme)\n",
    "\n",
    "* [jupyter](https://github.com/jupyter/jupyter-sphinx-theme/):\n",
    "  [example](http://nbsphinx.readthedocs.io/en/jupyter-theme/),\n",
    "  [usage](https://github.com/spatialaudio/nbsphinx/compare/jupyter-theme^...jupyter-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)."
   ]
  }
 ],
 "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.5.2+"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}
