#!/usr/bin/env python
# coding: utf-8
# This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/.
# # Using `toctree` In A Notebook
#
# 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.
# Those can be used to pull in further source files (which themselves can contain further `toctree` directives).
#
# With `nbsphinx` it is possible to get a similar effect within a Jupyter notebook using the
# `"nbsphinx-toctree"` cell tag or cell metadata.
# Markdown cells with `"nbsphinx-toctree"` tag/metadata are not converted like "normal" Markdown cells.
# 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.
# External links can also be used, but they will not be visible in the LaTeX output.
#
# If there is a section title in the selected cell,
# it is used as `toctree` caption (but it also works without a title).
#
#
#
# Note
#
# All other content of such a cell is *ignored*!
#
#
#
# If you are satisfied with the default settings,
# you can simply use `"nbsphinx-toctree"` as a cell tag.
#
# Alternatively, you can store `"nbsphinx-toctree"` cell metadata.
# Use ...
#
# ```json
# {
# "nbsphinx-toctree": {}
# }
# ```
#
# ... for the default settings, ...
#
# ```json
# {
# "nbsphinx-toctree": {
# "maxdepth": 2
# }
# }
# ```
#
# ... for setting the `:maxdepth:` option, or...
#
# ```json
# {
# "nbsphinx-toctree": {
# "hidden": true
# }
# }
# ```
#
# ... for setting the `:hidden:` option.
#
# Of course, multiple options can be used at the same time, e.g.
#
# ```json
# {
# "nbsphinx-toctree": {
# "maxdepth": 3,
# "numbered": true
# }
# }
# ```
#
# For more options, have a look a the [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree).
# 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).
#
#
#
# Note
#
# 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.
# All content below the `toctree` cell will appear after the table of contents/inserted section, respectively.
# 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.
# Multiple `toctree` cells in a row should be fine, though.
#
#
#
# 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).
# It also contains a section title which will be used as `toctree` caption
# (which also will only be visible in the HTML output).
# The following section title will be converted to the `toctree` caption.
#
# ## A sub-toctree
#
# [A Notebook that's just a "toctree" Target](../yet-another.ipynb)
#
# [An External Link (HTML only)](https://nbsphinx.readthedocs.io/)
#
# Only the first section title (optional) and links to other source files (and external links) are used,
# all other cell content (like this very sentence) is ignored!