{
 "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 `toctree` In A Notebook\n",
    "\n",
    "In Sphinx-based documentation, there is typically a file called `index.rst` which contains one or more [toctree](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree) directives.\n",
    "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",
    "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",
    "If there is a section title in the selected cell,\n",
    "it is used as `toctree` caption (but it also works without a title).\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "Note\n",
    "\n",
    "All other content of such a cell is *ignored*!\n",
    "\n",
    "</div>\n",
    "\n",
    "If you are satisfied with the default settings,\n",
    "you can simply use `nbsphinx-toctree` as a cell tag.\n",
    "\n",
    "Alternatively, you can store `nbsphinx-toctree` cell metadata.\n",
    "Use ...\n",
    "\n",
    "```json\n",
    "{\n",
    "  \"nbsphinx-toctree\": {}\n",
    "}\n",
    "```\n",
    "\n",
    "... for the default settings, ...\n",
    "\n",
    "```json\n",
    "{\n",
    "  \"nbsphinx-toctree\": {\n",
    "    \"maxdepth\": 2\n",
    "  }\n",
    "}\n",
    "```\n",
    "\n",
    "... for setting the `:maxdepth:` option, or...\n",
    "\n",
    "```json\n",
    "{\n",
    "  \"nbsphinx-toctree\": {\n",
    "    \"hidden\": true\n",
    "  }\n",
    "}\n",
    "```\n",
    "\n",
    "... for setting the `:hidden:` option.\n",
    "\n",
    "Of course, multiple options can be used at the same time, e.g.\n",
    "\n",
    "```json\n",
    "{\n",
    "  \"nbsphinx-toctree\": {\n",
    "    \"maxdepth\": 3,\n",
    "    \"numbered\": true\n",
    "  }\n",
    "}\n",
    "```\n",
    "\n",
    "For more options, have a look a the [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree).\n",
    "All options can be used -- except `:glob:`, which can only be used in [rst files](../a-normal-rst-file.rst) and in [raw reST cells](../raw-cells.ipynb#reST).\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "Note\n",
    "\n",
    "In HTML output, a `toctree` cell generates an in-line table of contents (containing links) at its position in the notebook, whereas in the LaTeX output, a new (sub-)section with the actual content is inserted at its position.\n",
    "All content below the `toctree` cell will appear after the table of contents/inserted section, respectively.\n",
    "If you want to use the LaTeX output, it is recommended that you don't add further cells below a `toctree` cell, otherwise their content may appear at unexpected places.\n",
    "Multiple `toctree` cells in a row should be fine, though.\n",
    "\n",
    "</div>\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",
    "It also contains a section title which will be used as `toctree` caption\n",
    "(which also will only be visible in the HTML output)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": [
     "nbsphinx-toctree"
    ]
   },
   "source": [
    "The following section title will be converted to the `toctree` caption.\n",
    "\n",
    "## A sub-toctree\n",
    "\n",
    "[A Notebook that's just a \"toctree\" Target](../yet-another.ipynb)\n",
    "\n",
    "[An External Link (HTML only)](https://nbsphinx.readthedocs.io/)\n",
    "\n",
    "Only the first section title (optional) and links to other source files (and external links) are used,\n",
    "all other cell content (like this very sentence) is ignored!"
   ]
  }
 ],
 "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
}