1.4. Table of Contents Tree¶
Now would be a good time to introduce the .. toctree::
. One of the
main concepts in Sphinx is that it allows multiple pages to be combined
into a cohesive hierarchy. Since reStructuredText does not have facilities
to interconnect several documents, or split documents into multiple output
files, Sphinx uses a custom directive to add relations between the single
files the documentation is made of, as well as tables of contents.
The .. toctree::
directive is the central element and a fundamental
part of this structure. Consider this example:
-
.. toctree::
¶ For more details, see
toctree
directive.- The example
1 2 3 4 5 6
.. toctree:: :maxdepth: 2 install support (many more files listed here)
- Which gives
index ├── install ├── support ├── (many more files here) ├── (many more sub-files here)
The above directive example will output a TOC in
the page where it occurs, using the individual TOCs (including “sub-TOC trees”)
of the files given in the directive body. The :maxdepth: 2
argument
tells Sphinx to include 2 levels of headers in it’s output. It will output
the 2 top-level headers of the pages listed; by default, all levels are
included. This also tells Sphinx that the other pages are sub-pages
of the current page, creating a “tree” structure of the pages.
This accomplishes two things:
Tables of contents from all those files are inserted, with a maximum depth of argument
:maxdepth:
, that means one nested heading... toctree::
directives in those files are also taken into account.Sphinx knows that the relative order of the files
install
,support
and so forth, and it knows that they are children of the shown file, the library index. From this information it generates “next chapter”, “previous chapter” and “parent chapter” links.
In the end, all files included in the build process must occur in (only) one
.. toctree::
directive; Sphinx will emit a warning if it finds a file
that is not included, because that means that this file will not be reachable
through standard navigation.
The special file index.rst
at the root of the source directory is the
“root” of the TOC tree hierarchy; from it the “Contents” page is generated.
1.4.2. Secondary sub-TOC trees¶
Collections of documents are mostly given their own table of content on an
individual page (see, for example: Appendix and Glossary).
In these cases, the page containing the .. toctree::
serves as a sort
of intro page for the collection. That intro must, itself, be included in the
Sidebar navigation menu. The contents of a
.. toctree::
appear as section links in another .. toctree::
it
is included in. That is, if a .. toctree::
in index.rst
lists
.. glossary::
, and glossary.rst
has a .. toctree::
, then
the contents of that second .. toctree::
will appear in the
Sidebar navigation menu, as sub-items to
Glossary.
Indeed, this is precisely the case in this Li-Pro.Net Sphinx Primer document currently.
1.4.3. How this document uses main and secondary TOC¶
Major topics get a
.. toctree::
inindex.rst
Major topics include things like:
Each major parts (Extensions, Themes,…)
Large, general categories like Releases, Contributing, or Building
Major topic tables of content include both sub-collection intro pages and also individual pages that don’t fit into a sub-collection.
The
:caption:
attribute of the.. toctree::
directive may but not must defines the section label in the Sidebar navigation menu.Within a large topic, documents are grouped into collections of related pages, defined by a
.. toctree::
on a topic intro page.Intro pages (pages that contain secondary
.. toctree::
directives) may include additional content, introducing the collection or providing contextual way-finding. However, this is not always necessary or desirable. Use your judgment, and avoid stating things just for the sake of having some text. (“Here are the pages in this collection.”)We also (very occasionally) include
.. toctree::
directives in sub-collection pages, such as:
Tip
If it not obvious where a new document should appear in the navigation, the best practice is to simply ask about it in the GitHub issue driving the new page.
Note
For way-finding purposes, we sometimes create an Unordered (bullet) Lists of page links rather than a
.. toctree::
directive (for example, seeindex.rst
). We do this when using a.. toctree::
would create redundant links in the Sidebar navigation menu.