Continued: Use the last image in a notebook as the default thumbnail

doc/configuration.ipynb

@@ -387,7 +387,8 @@
     "(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",
+    "[thumbnail gallery](subdir/gallery.ipynb). Thumbnails specified\n",
+    "in notebooks will override those provided in this dictionary.\n",
     "\n",
     "See [Specifying Thumbnails](gallery/thumbnail-from-conf-py.ipynb)."
    ]

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,100 @@
+{
+ "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 Thumbnail\n",
+    "\n",
+    "By default,\n",
+    "the last image output of a notebook will be used as its thumbnail.\n",
+    "Without an image output, a placeholder will be used.\n",
+    "See [a notebook with no thumbnail](no-thumbnail.ipynb) for an example.\n",
+    "\n",
+    "However, if a thumbnail is explicitly assigned by\n",
+    "[Using Cell Metadata to Select a Thumbnail](cell-metadata.ipynb),\n",
+    "[Using a Cell Tag to Select a Thumbnail](cell-tag.ipynb) or\n",
+    "[Specifying a Thumbnail File](thumbnail-from-conf-py.ipynb),\n",
+    "these methods will take precedence."
+   ]
+  },
+  {
+   "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,\n",
+    "so its last image output will be used as the thumbnail."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "display(fig)\n",
+    "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 (ipykernel)",
+   "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.11.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

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

@@ -70,8 +70,9 @@
     "Only links and the first section title are scanned,\n",
     "everything else is ignored.\n",
     "\n",
+    "* [Last Image Is Used by Default](default-thumbnail.ipynb)\n",
     "* [Using a Cell Tag to Select a Thumbnail](cell-tag.ipynb)\n",
-    "* [Using Cell Metadata to Select a Thumbnail](cell-metadata.ipynb)\n",
+    "* [Using Cell Metadata to Select a Thumbnail and Provide a Tooltip](cell-metadata.ipynb)\n",
     "* [Choosing from Multiple Outputs](multiple-outputs.ipynb)\n",
     "* [No Thumbnail Available](no-thumbnail.ipynb)\n",
     "* [Specifying a Thumbnail File](thumbnail-from-conf-py.ipynb)\n",
@@ -98,7 +99,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.1"
+   "version": "3.11.2"
   }
  },
  "nbformat": 4,

doc/gallery/thumbnail-from-conf-py.ipynb

@@ -15,9 +15,10 @@
    "source": [
     "# Specifying Thumbnails in `conf.py`\n",
     "\n",
-    "This notebook doesn't contain any thumbnail metadata.\n",
-    "\n",
-    "But in the file [conf.py](../conf.py),\n",
+    "This notebook doesn't contain a `nbsphinx-thumbnail`\n",
+    "[cell tag](cell-tag.ipynb) nor\n",
+    "[cell metadata](cell-metadata.ipynb).\n",
+    "Instead, in the file [conf.py](../conf.py),\n",
     "a thumbnail is specified (via the\n",
     "[nbsphinx_thumbnails](../configuration.ipynb#nbsphinx_thumbnails)\n",
     "option),\n",
@@ -48,15 +49,6 @@
     "we are creating an image file here:"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%matplotlib agg"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -74,7 +66,8 @@
    "source": [
     "fig, ax = plt.subplots()\n",
     "ax.plot([4, 8, 15, 16, 23, 42])\n",
-    "fig.savefig('a-local-file.png')"
+    "fig.savefig('a-local-file.png')\n",
+    "plt.close()  # avoid plotting the figure"
    ]
   },
   {
@@ -97,6 +90,25 @@
     "\n",
     "Please note that the notebook name does *not* contain the `.ipynb` suffix."
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note that the following plot is *not* used as a thumbnail\n",
+    "because the `nbsphinx_thumbnails` setting overrides\n",
+    "[the default behavior](default-thumbnail.ipynb)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig, ax = plt.subplots(figsize=[6, 3])\n",
+    "ax.plot([4, 9, 7, 20, 6, 33, 13, 23, 16, 62, 8], 'r:');"
+   ]
   }
  ],
  "metadata": {
@@ -115,7 +127,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.1"
+   "version": "3.11.2"
   }
  },
  "nbformat": 4,