Add gallery feature

Closes spatialaudio#254.

.gitignore

@@ -7,3 +7,4 @@ nbsphinx.egg-info/
 .python-version
 .vscode
 doc/_build
+doc/gallery/a-local-file.png

doc/a-normal-rst-file.rst

@@ -217,3 +217,25 @@ see https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/156.
 There is an alternative Sphinx extension for creating bibliographies:
 https://bitbucket.org/wnielson/sphinx-natbib/.
 However, this project seems to be abandoned (last commit in 2011).
+
+
+Thumbnail Galleries
+-------------------
+
+With ``nbsphinx`` you can create thumbnail galleries in notebook files
+as described in :ref:`/subdir/gallery.ipynb`.
+
+If you like, you can also create such galleries in reST files
+using the ``nbgallery`` directive.
+
+It takes the same parameters as the `toctree`__ directive.
+
+__ https://www.sphinx-doc.org/en/master/usage/restructuredtext/
+    directives.html#directive-toctree
+
+.. nbgallery::
+    :hidden:
+    :glob:
+    :reversed:
+
+    gallery/*-rst

doc/conf.py

@@ -14,6 +14,10 @@
     'sphinxcontrib.rsvgconverter',  # for SVG->PDF conversion in LaTeX output
 ]
 
+import sphinx_gallery
+html_static_path = [sphinx_gallery.glr_path_static()]
+html_css_files = ['gallery.css']
+
 # Exclude build directory and Jupyter backup files:
 exclude_patterns = ['_build', '**.ipynb_checkpoints']
 
@@ -35,6 +39,11 @@
 # Environment variables to be passed to the kernel:
 os.environ['MY_DUMMY_VARIABLE'] = 'Hello from conf.py!'
 
+nbsphinx_thumbnails = {
+    'gallery/thumbnail-from-conf-py': 'gallery/a-local-file.png',
+    'gallery/*-rst': '_static/copy-button.svg',
+}
+
 # This is processed by Jinja2 and inserted before each notebook
 nbsphinx_prolog = r"""
 {% set docname = 'doc/' + env.doc2path(env.docname, base=None) %}

doc/gallery/cell-metadata.ipynb

@@ -0,0 +1,120 @@
+{
+ "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": [
+    "# Using Cell Metadata to Select a Thumbnail\n",
+    "\n",
+    "If the [nbsphinx-thumbnail](cell-tag.ipynb) cell tag is not enough,\n",
+    "you can use cell metadata to specify more options.\n",
+    "\n",
+    "The last cell in this notebook has this metadata:\n",
+    "\n",
+    "```json\n",
+    "{\n",
+    "    \"nbsphinx-thumbnail\": {\n",
+    "        \"tooltip\": \"This tooltip message was defined in cell metadata\"\n",
+    "    }\n",
+    "}\n",
+    "```\n",
+    "\n",
+    "If there are multiple outputs in the selected cell,\n",
+    "the last one is used.\n",
+    "See [Choosing from Multiple Outputs](multiple-outputs.ipynb)\n",
+    "for how to select a specific output."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "import numpy as np"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plt.rcParams['image.cmap'] = 'coolwarm'\n",
+    "plt.rcParams['image.origin'] = 'lower'"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Some example data stolen from\n",
+    "https://matplotlib.org/examples/pylab_examples/pcolor_demo.html:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "x, y = np.meshgrid(np.arange(-3, 3, 0.1), np.arange(-2, 2, 0.1))\n",
+    "z = (1 - x / 2 + x ** 5 + y ** 3) * np.exp(-x ** 2 - y ** 2)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "zmax = np.max(np.abs(z))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "nbsphinx-thumbnail": {
+     "tooltip": "This tooltip message was defined in cell metadata"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "fig, ax = plt.subplots()\n",
+    "ax.imshow(z, vmin=-zmax, vmax=zmax)"
+   ]
+  }
+ ],
+ "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.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

doc/gallery/cell-tag.ipynb

@@ -0,0 +1,81 @@
+{
+ "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": [
+    "# Using a Cell Tag to Select a Thumbnail\n",
+    "\n",
+    "You can select any code cell (with appropriate output)\n",
+    "by tagging it with the `nbsphinx-thumbnail` tag.\n",
+    "\n",
+    "If there are multiple outputs in the selected cell,\n",
+    "the last one is used.\n",
+    "See [Choosing from Multiple Outputs](multiple-outputs.ipynb)\n",
+    "for how to select a specific output.\n",
+    "If you want to show a tooltip, have a look at\n",
+    "[Using Cell Metadata to Select a Thumbnail](cell-metadata.ipynb)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The following cell has the `nbsphinx-thumbnail` tag:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "nbsphinx-thumbnail"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "fig, ax = plt.subplots(figsize=[6, 3])\n",
+    "ax.plot([4, 9, 7, 20, 6, 33, 13, 23, 16, 62, 8])"
+   ]
+  }
+ ],
+ "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.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

doc/gallery/due-rst.ipynb

@@ -0,0 +1,46 @@
+{
+ "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": [
+    "# Dummy Notebook 2 for Gallery\n",
+    "\n",
+    "This is a dummy file just to fill\n",
+    "[the gallery in the reST file](../a-normal-rst-file.rst#thumbnail-galleries).\n",
+    "\n",
+    "The thumbnail image is assigned in [conf.py](../conf.py)."
+   ]
+  }
+ ],
+ "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.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

doc/gallery/multiple-outputs.ipynb

@@ -0,0 +1,79 @@
+{
+ "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": [
+    "# Choosing from Multiple Outputs\n",
+    "\n",
+    "By default, the last output of the selected cell is used as a thumbnail.\n",
+    "If that's what you want, you can simply use the\n",
+    "[nbsphinx-thumbnail](cell-tag.ipynb) cell tag.\n",
+    "\n",
+    "If you want to specify one of multiple outputs,\n",
+    "you can add a (zero-based) `\"output-index\"`\n",
+    "to your `\"nbsphinx-thumbnail\"` cell metadata.\n",
+    "\n",
+    "The following cell has this metadata,\n",
+    "selecting the third output to be used as thumbnail in\n",
+    "[the gallery](../subdir/gallery.ipynb).\n",
+    "\n",
+    "```json\n",
+    "{\n",
+    "    \"nbsphinx-thumbnail\": {\n",
+    "        \"output-index\": 2\n",
+    "    }\n",
+    "}\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "nbsphinx-thumbnail": {
+     "output-index": 2
+    }
+   },
+   "outputs": [],
+   "source": [
+    "from IPython.display import Image\n",
+    "\n",
+    "display(Image(url='https://jupyter.org/assets/nav_logo.svg'))\n",
+    "print('Hello!')\n",
+    "display(Image(filename='../images/notebook_icon.png'))\n",
+    "display(Image(url='https://www.python.org/static/img/python-logo-large.png', embed=True))"
+   ]
+  }
+ ],
+ "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.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}