Demonstrate default thumbnails in the documentation

doc/gallery/cell-tag.ipynb

@@ -39,7 +39,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The following cell has the `nbsphinx-thumbnail` tag:"
+    "The following cell has the `nbsphinx-thumbnail` tag, which will take precedence over the default of the last image in the notebook:"
    ]
   },
   {
@@ -55,6 +55,23 @@
     "fig, ax = plt.subplots(figsize=[6, 3])\n",
     "ax.plot([4, 9, 7, 20, 6, 33, 13, 23, 16, 62, 8])"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Although the next cell has an image, it won't be used as the thumbnail, due to the tag on the one above."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig, ax = plt.subplots(figsize=[6, 3])\n",
+    "ax.scatter(range(10), [0, 8, 9, 1, -8, -10, -3, 7, 10, 4])"
+   ]
   }
  ],
  "metadata": {

doc/gallery/default-thumbnail.ipynb

@@ -0,0 +1,83 @@
+{
+ "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": [
+    "# Default Thumbnails\n",
+    "\n",
+    "By default, a notebook with an image output will use the last of these as its thumbnail. Without an image output, a placeholder will be used. See [a notebook with no thumbnail](no-thumbnail.ipynb) for an example.\n",
+    "\n",
+    "However, if a thumbnail is explicitly assigned by [Using Cell Metadata to Select a Thumbnail](cell-metadata.ipynb), [Using a Cell Tag to Select a Thumbnail](cell-tag.ipynb) or [Specifying Thumbnails in `conf.py`](thumbnail-from-conf-py.ipynb), these methods will take precedence: cell tags and metadata are higher priority than in `conf.py`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "import numpy as np"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Although the next cell contains an image (a plot), it won't be used as the thumbnail because it's not the last in the notebook, and we haven't explicitly tagged it."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig, ax = plt.subplots(figsize=[6, 3])\n",
+    "x = np.linspace(-5, 5, 50)\n",
+    "ax.plot(x, np.sinc(x))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "But the next cell is the last containing an image in the notebook, so it will be used as the thumbnail."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig, ax = plt.subplots(figsize=[6, 3])\n",
+    "x = np.linspace(-5, 5, 50)\n",
+    "ax.plot(x, -np.sinc(x), color='red')"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

doc/gallery/gallery-with-nested-documents.ipynb

@@ -73,6 +73,7 @@
     "* [Using a Cell Tag to Select a Thumbnail](cell-tag.ipynb)\n",
     "* [Using Cell Metadata to Select a Thumbnail](cell-metadata.ipynb)\n",
     "* [Choosing from Multiple Outputs](multiple-outputs.ipynb)\n",
+    "* [Default Thumbnails](default-thumbnail.ipynb)\n",
     "* [No Thumbnail Available](no-thumbnail.ipynb)\n",
     "* [Specifying a Thumbnail File](thumbnail-from-conf-py.ipynb)\n",
     "\n",