.
Using toctree In A Notebook¶
In 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).
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 …
{
"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.
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 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).