doc/gallery/thumbnail-from-conf-py.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": [
    "# Specifying Thumbnails in `conf.py`\n",
    "\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",
    "which will be used in the [gallery](gallery-with-nested-documents.ipynb).\n",
    "\n",
    "The keys in the `nbsphinx_thumbnails` dictionary can contain wildcards,\n",
    "which behave very similarly to the\n",
    "[html_sidebars](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars)\n",
    "option.\n",
    "\n",
    "The thumbnail files can be local image files somewhere in the source directory,\n",
    "but you'll need to create at least one\n",
    "[link](../markdown-cells.ipynb#Links-to-Local-Files)\n",
    "to them in order to copy them to the HTML output directory.\n",
    "\n",
    "You can also use files from the `_static` directory\n",
    "(which contains all files in your [html_static_path](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path)).\n",
    "\n",
    "If you want, you can also use files from the `_images` directory,\n",
    "which contains all notebook outputs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To demonstrate this feature,\n",
    "we are creating an image file here:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots()\n",
    "ax.plot([4, 8, 15, 16, 23, 42])\n",
    "fig.savefig('a-local-file.png')\n",
    "plt.close()  # avoid plotting the figure"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Please note that the previous cell doesn't have any outputs,\n",
    "but it has generated a file named `a-local-file.png` in the notebook's directory.\n",
    "\n",
    "We have to create a link to this file (which is a good idea anyway):\n",
    "[a-local-file.png](a-local-file.png).\n",
    "\n",
    "Now we can use this file in our [conf.py](../conf.py) like this:\n",
    "\n",
    "```python\n",
    "nbsphinx_thumbnails = {\n",
    "    'gallery/thumbnail-from-conf-py': 'gallery/a-local-file.png',\n",
    "}\n",
    "```\n",
    "\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": {
  "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
}