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

.. 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.

Note

The TOC Tree is also used for generating the navigation elements inside Sphinx. It is quite important, and one of the most powerful concepts in Sphinx.

1.4.1. Sidebar navigation menu

The index.rst file serves as a front-page to the documentation and contains the main tables of content, defined using .. toctree:: directives. These .. toctree:: directives control the sidebar navigation menu. To add a new document to a table of content, add the file name (without the .rst extension) to the relevant list of file names in index.rst or any other (but only one) “sub-TOC trees”.

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:: in index.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:

  • BibTeX Citations,

  • Spelling Checker,

  • …

  • Read the Docs Sphinx Theme,

  • …

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, see index.rst). We do this when using a .. toctree:: would create redundant links in the Sidebar navigation menu.