#!/usr/bin/env python
# coding: utf-8

# This notebook is part of the `nbsphinx` documentation: http://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](http://www.sphinx-doc.org/markup/toctree.html) directives.
# Those can be used to pull in further source files (which themselves can contain `toctree` directives).
# 
# With `nbsphinx` it is possible to get a similar effect within a Jupyter notebook using the `"nbsphinx-toctree"` cell metadata.
# Markdown cells with `"nbsphinx-toctree"` 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 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>
# 
# Use ...
# 
#     "nbsphinx-toctree": {}
# 
# ... for the default settings, ...
# 
#     "nbsphinx-toctree": {
#       "maxdepth": 2
#     }
# 
# ... for setting the `:maxdepth:` option, or...
# 
#     "nbsphinx-toctree": {
#       "hidden": true
#     }
# 
# ... for setting the `:hidden:` option.
# 
# Of course, multiple options can be used at the same time, e.g.
# 
#     "nbsphinx-toctree": {
#       "maxdepth": 3,
#       "numbered": true
#     }
# 
# For more options, have a look a the [Sphinx documentation](http://www.sphinx-doc.org/markup/toctree.html).
# 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 that in the 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"` metadata 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.

# 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)](http://nbsphinx.readthedocs.io/)
# 
# Only the first section title (optional) and links to other sources (and external links) are used, all other cell content is ignored!