#!/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).
# 
# <div class="alert alert-info">
# 
# Note
# 
# All other content of such a cell is *ignored*!
# 
# </div>
# 
# 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).
# 
# <div class="alert alert-info">
# 
# 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.
# 
# </div>
# 
# 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!