From 23869df17e14bbb3838a496d304d0175175b2937 Mon Sep 17 00:00:00 2001 From: Matthias Geier Date: Sun, 1 Jan 2023 22:24:08 +0100 Subject: [PATCH] DOC: Separate notebooks for different gallery types --- doc/a-normal-rst-file.rst | 61 +++++----- doc/gallery/gallery-with-links.ipynb | 90 +++++++++++++++ .../gallery-with-nested-documents.ipynb | 106 ++++++++++++++++++ doc/gallery/multiple-outputs.ipynb | 6 +- doc/gallery/no-thumbnail.ipynb | 6 +- doc/gallery/thumbnail-from-conf-py.ipynb | 6 +- doc/subdir/gallery.ipynb | 61 ++-------- doc/subdir/toctree.ipynb | 14 +-- 8 files changed, 259 insertions(+), 91 deletions(-) create mode 100644 doc/gallery/gallery-with-links.ipynb create mode 100644 doc/gallery/gallery-with-nested-documents.ipynb diff --git a/doc/a-normal-rst-file.rst b/doc/a-normal-rst-file.rst index 443d1f3d..47994665 100644 --- a/doc/a-normal-rst-file.rst +++ b/doc/a-normal-rst-file.rst @@ -267,15 +267,48 @@ here. Instead, the footnote citations are placed into the footnotes of their respective pages. +Thumbnail Link Galleries (HTML only) +------------------------------------- + +In some case it is desired to create thumbnail links to existing notebooks, +already included in a ``toctree``. This can be used e.g. to link to a subset +of notebooks from API documentation to highlight the use of some functionality. +For this there is a dedicated ``nblinkgallery`` directive. + +The following example gallery was created using: + +.. code-block:: rest + + .. nblinkgallery:: + :caption: A few links + :name: rst-link-gallery + + gallery/multiple-outputs + gallery/no-thumbnail + gallery/cell-metadata + orphan + +.. nblinkgallery:: + :caption: A few links + :name: rst-link-gallery + + gallery/multiple-outputs + gallery/no-thumbnail + gallery/cell-metadata + orphan + +.. seealso:: + + `Link Galleries in Jupyter Notebooks `_ + + Thumbnail Galleries ------------------- With ``nbsphinx`` you can create thumbnail galleries in notebook files -as described in :ref:`/subdir/gallery.ipynb`. - +as described in :ref:`/gallery/gallery-with-nested-documents.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/ @@ -305,25 +338,3 @@ The following example gallery was created using: :reversed: gallery/*-rst - - -Thumbnail Links Galleries (HTML only) -------------------------------------- - -In some case it is desired to just create thumbnail links to existing notebooks, -already included in a ``toctree``. This can be used e.g. to link to a subset -of notebooks from API documentation to highlight the use of some functionality. -For this there is a dedicated ``nblinkgallery`` directive. - -The following example gallery was created using: - -.. code-block:: rest - - .. nblinkgallery:: - gallery/multiple-outputs - gallery/no-thumbnail - -.. nblinkgallery:: - gallery/multiple-outputs - gallery/no-thumbnail - diff --git a/doc/gallery/gallery-with-links.ipynb b/doc/gallery/gallery-with-links.ipynb new file mode 100644 index 00000000..08cd1e3b --- /dev/null +++ b/doc/gallery/gallery-with-links.ipynb @@ -0,0 +1,90 @@ +{ + "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": [ + "# Gallery With Links (HTML only)\n", + "\n", + "Contrary to\n", + "[nbsphinx-gallery](gallery-with-nested-documents.ipynb),\n", + "the cell tag/metadata `nbsphinx-link-gallery`\n", + "creates a gallery from notebooks (and other source) files\n", + "without including them as sub-sections.\n", + "Other than that, it works in a similar way,\n", + "but only the options\n", + "`\"name\"`,\n", + "`\"caption\"` and\n", + "`\"reversed\"` are supported.\n", + "In LaTeX output, this has no effect.\n", + "The cell is ignored and nothing is added to the LaTeX document.\n", + "\n", + "In reST files\n", + "(and [raw reST cells](../raw-cells.ipynb#reST)),\n", + "the\n", + "[nblinkgallery](../a-normal-rst-file.rst#thumbnail-link-galleries-html-only)\n", + "directive can be used.\n", + "\n", + "The following Markdown cell\n", + "has the `nbsphinx-link-gallery` tag,\n", + "which turns the contained links into a gallery\n", + "and uses the first section title as `caption`:" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "tags": [ + "nbsphinx-link-gallery" + ] + }, + "source": [ + "## This is a thumbnail gallery with links to existing documents:\n", + "\n", + "This paragraph will be ignored.\n", + "Only links are taken into account.\n", + "\n", + "## This section title will be ignored\n", + "\n", + "... because only the first title in this cell is used.\n", + "\n", + "* [Dummy Notebook 2](due-rst.pct.py)\n", + "* [An Orphan Notebook](../orphan.ipynb)\n", + "* [Notebook About Code Cells](../code-cells.ipynb)\n", + "* [Thumbnail With a Tooltip](cell-metadata.ipynb)\n", + "* [A Page About Contributing (Not a Notebook)](../contributing.rst)\n", + "* [A Page Using reStructuredText (Not a Notebook)](../a-normal-rst-file.rst)" + ] + } + ], + "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.1" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/doc/gallery/gallery-with-nested-documents.ipynb b/doc/gallery/gallery-with-nested-documents.ipynb new file mode 100644 index 00000000..56316932 --- /dev/null +++ b/doc/gallery/gallery-with-nested-documents.ipynb @@ -0,0 +1,106 @@ +{ + "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": [ + "# Gallery With Nested Documents\n", + "\n", + "You can create\n", + "[thumbnail galleries in reST files](../a-normal-rst-file.rst#thumbnail-galleries),\n", + "but you can also create such galleries in Jupyter notebooks\n", + "by adding the `nbsphinx-gallery`\n", + "cell tag or metadata,\n", + "which is used just like the\n", + "[nbsphinx-toctree](../subdir/toctree.ipynb) cell tag/metadata.\n", + "For possible options, see the [toctree](../subdir/toctree.ipynb) notebook.\n", + "\n", + "
\n", + "\n", + "Note\n", + "\n", + "In LaTeX output this behaves just like ``toctree``,\n", + "i.e. no thumbnail gallery is shown,\n", + "but the linked files are included in the document.\n", + "\n", + "Like with ``toctree`` you should avoid adding content\n", + "after a gallery (except other toctrees and galleries)\n", + "because this content would appear in the LaTeX output\n", + "*after* the content of all included source files,\n", + "which is probably not what you want.\n", + "\n", + "
\n", + "\n", + "The following cell has the `nbsphinx-gallery` tag,\n", + "which creates a thumbnail gallery.\n", + "The *first* section title in that cell (if available)\n", + "is used as `caption` (unless it is already given in the metadata).\n", + "\n", + "The notebooks in the following gallery describe different ways\n", + "how to select which images are used as thumbnails.\n", + "The notebooks are added as sub-sections under the current section,\n", + "just like when using ``toctree``.\n", + "If you want to create a gallery from links to notebooks\n", + "that are already included somewhere else,\n", + "you can use [nbsphinx-link-gallery](gallery-with-links.ipynb)." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "tags": [ + "nbsphinx-gallery" + ] + }, + "source": [ + "This section title will be used as ``caption``:\n", + "\n", + "## This is a thumbnail gallery with sub-documents:\n", + "\n", + "This paragraph will be ignored.\n", + "Only links and the first section title are scanned,\n", + "everything else is ignored.\n", + "\n", + "* [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", + "* [No Thumbnail Available](no-thumbnail.ipynb)\n", + "* [Specifying a Thumbnail File](thumbnail-from-conf-py.ipynb)\n", + "\n", + "## This section title will be ignored\n", + "\n", + "... because only the first title in this cell is used." + ] + } + ], + "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.1" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/doc/gallery/multiple-outputs.ipynb b/doc/gallery/multiple-outputs.ipynb index 4bbbeb78..2c7e110b 100644 --- a/doc/gallery/multiple-outputs.ipynb +++ b/doc/gallery/multiple-outputs.ipynb @@ -25,7 +25,7 @@ "\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", + "[the gallery](gallery-with-nested-documents.ipynb).\n", "\n", "```json\n", "{\n", @@ -57,7 +57,7 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -71,7 +71,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.7.6" + "version": "3.11.1" } }, "nbformat": 4, diff --git a/doc/gallery/no-thumbnail.ipynb b/doc/gallery/no-thumbnail.ipynb index f5f584ed..dc9ac890 100644 --- a/doc/gallery/no-thumbnail.ipynb +++ b/doc/gallery/no-thumbnail.ipynb @@ -18,13 +18,13 @@ "This notebook doesn't contain any thumbnail metadata.\n", "\n", "It should be displayed with the default thumbnail image in the\n", - "[gallery](../subdir/gallery.ipynb)." + "[gallery](gallery-with-nested-documents.ipynb)." ] } ], "metadata": { "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -38,7 +38,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.7.6" + "version": "3.11.1" } }, "nbformat": 4, diff --git a/doc/gallery/thumbnail-from-conf-py.ipynb b/doc/gallery/thumbnail-from-conf-py.ipynb index 5962be3a..8020f96e 100644 --- a/doc/gallery/thumbnail-from-conf-py.ipynb +++ b/doc/gallery/thumbnail-from-conf-py.ipynb @@ -21,7 +21,7 @@ "a thumbnail is specified (via the\n", "[nbsphinx_thumbnails](../configuration.ipynb#nbsphinx_thumbnails)\n", "option),\n", - "which will be used in the [gallery](../subdir/gallery.ipynb).\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", @@ -101,7 +101,7 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -115,7 +115,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.7.6" + "version": "3.11.1" } }, "nbformat": 4, diff --git a/doc/subdir/gallery.ipynb b/doc/subdir/gallery.ipynb index 34db8eda..a16a0d93 100644 --- a/doc/subdir/gallery.ipynb +++ b/doc/subdir/gallery.ipynb @@ -42,69 +42,30 @@ "You can load your CSS files with\n", "[html_css_files](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files).\n", "\n", - "You can create\n", - "[Thumbnail Galleries in reST Files](../a-normal-rst-file.rst#thumbnail-galleries)\n", - "and you can create galleries by adding the `\"nbsphinx-gallery\"`\n", - "cell tag or metadata to notebooks,\n", - "which is used just like the\n", - "[\"nbsphinx-toctree\"](toctree.ipynb) cell tag/metadata.\n", - "\n", - "For possible options, see the [toctree](toctree.ipynb) notebook.\n", - "\n", - "
\n", - "\n", - "Note\n", - "\n", - "In LaTeX output this behaves just like ``toctree``,\n", - "i.e. no thumbnail gallery is shown,\n", - "but the linked files are included in the document.\n", - "\n", - "Like with ``toctree`` you should avoid adding content\n", - "after a gallery (except other toctrees and galleries)\n", - "because this content would appear in the LaTeX output\n", - "*after* the content of all included source files,\n", - "which is probably not what you want.\n", - "\n", - "
\n", - "\n", - "The following cell has the `\"nbsphinx-gallery\"` tag,\n", - "which creates a thumbnail gallery.\n", - "The *first* section title in that cell (if available)\n", - "is used as `\"caption\"` (unless it's given in the metadata).\n", - "\n", - "The notebooks in the following gallery describe different ways\n", - "how to select which images are used as thumbnails." + "The following sections present\n", + "two different ways of creating thumbnail galleries\n", + "in Jupyter notebooks\n", + "and show how thumbnail images can be selected.\n", + "Thumbnail galleries can also be created in\n", + "[reStructuredText files](../a-normal-rst-file.rst#thumbnail-galleries)." ] }, { "cell_type": "markdown", "metadata": { "tags": [ - "nbsphinx-gallery" + "nbsphinx-toctree" ] }, "source": [ - "This section title will be used as ``:caption:``:\n", - "\n", - "## This is a thumbnail gallery:\n", - "\n", - "This line will be ignored.\n", - "\n", - "* [Using a Cell Tag to Select a Thumbnail](../gallery/cell-tag.ipynb)\n", - "* [Using Cell Metadata to Select a Thumbnail](../gallery/cell-metadata.ipynb)\n", - "* [Choosing from Multiple Outputs](../gallery/multiple-outputs.ipynb)\n", - "* [No Thumbnail Available](../gallery/no-thumbnail.ipynb)\n", - "* [Specifying a Thumbnail File](../gallery/thumbnail-from-conf-py.ipynb)\n", - "\n", - "## This section title will be ignored\n", - "\n", - "... because only the first title in this cell is used." + "* [Gallery With Nested Documents](../gallery/gallery-with-nested-documents.ipynb)\n", + "* [Gallery With Links (HTML only)](../gallery/gallery-with-links.ipynb)" ] } ], "metadata": { "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -118,7 +79,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.2" + "version": "3.11.1" } }, "nbformat": 4, diff --git a/doc/subdir/toctree.ipynb b/doc/subdir/toctree.ipynb index 6ecb51fe..1fd5009d 100644 --- a/doc/subdir/toctree.ipynb +++ b/doc/subdir/toctree.ipynb @@ -19,8 +19,8 @@ "Those can be used to pull in further source files (which themselves can contain further `toctree` directives).\n", "\n", "With `nbsphinx` it is possible to get a similar effect within a Jupyter notebook using the\n", - "`\"nbsphinx-toctree\"` cell tag or cell metadata.\n", - "Markdown cells with `\"nbsphinx-toctree\"` tag/metadata are not converted like \"normal\" Markdown cells.\n", + "`nbsphinx-toctree` cell tag or cell metadata.\n", + "Markdown cells with `nbsphinx-toctree` tag/metadata are not converted like \"normal\" Markdown cells.\n", "Instead, they are only scanned for links to other notebooks (or `*.rst` files and other Sphinx source files) and those links are added to a `toctree` directive.\n", "External links can also be used, but they will not be visible in the LaTeX output.\n", "\n", @@ -36,9 +36,9 @@ "\n", "\n", "If you are satisfied with the default settings,\n", - "you can simply use `\"nbsphinx-toctree\"` as a cell tag.\n", + "you can simply use `nbsphinx-toctree` as a cell tag.\n", "\n", - "Alternatively, you can store `\"nbsphinx-toctree\"` cell metadata.\n", + "Alternatively, you can store `nbsphinx-toctree` cell metadata.\n", "Use ...\n", "\n", "```json\n", @@ -94,7 +94,7 @@ "\n", "\n", "\n", - "The following cell is tagged with `\"nbsphinx-toctree\"` and contains a link to the notebook [yet-another.ipynb](../yet-another.ipynb) and an external link (which will only be visible in the HTML output).\n", + "The following cell is tagged with `nbsphinx-toctree` and contains a link to the notebook [yet-another.ipynb](../yet-another.ipynb) and an external link (which will only be visible in the HTML output).\n", "It also contains a section title which will be used as `toctree` caption\n", "(which also will only be visible in the HTML output)." ] @@ -122,7 +122,7 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, @@ -136,7 +136,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.7.6" + "version": "3.11.1" } }, "nbformat": 4,