This notebook is part of the nbsphinx
documentation: https://nbsphinx.readthedocs.io/.
toctree
In A NotebookIn Sphinx-based documentation, there is typically a file called index.rst
which contains one or more 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).
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 ...
{
"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.
All options can be used -- except :glob:
, which can only be used in rst files and in raw reST cells.
The following cell is tagged with "nbsphinx-toctree"
and contains a link to the notebook 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 Notebook that's just a "toctree" Target
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!