The TOC tree

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

Note

Simple “inclusion” of one file in another can be done with the include directive.

.. toctree::

This directive inserts a “TOC tree” at the current location, using the individual TOCs (including “sub-TOC trees”) of the documents given in the directive body. Relative document names (not beginning with a slash) are relative to the document the directive occurs in, absolute names are relative to the source directory. A numeric maxdepth option may be given to indicate the depth of the tree; by default, all levels are included. [1]

Consider this example (taken from the Python docs’ library reference index):

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more documents listed here)

This accomplishes two things:

• Tables of contents from all those documents are inserted, with a maximum depth of two, that means one nested heading. toctree directives in those documents are also taken into account.
• Sphinx knows that the relative order of the documents intro, strings and so forth, and it knows that they are children of the shown document, the library index. From this information it generates “next chapter”, “previous chapter” and “parent chapter” links.

Entries

Document titles in the toctree will be automatically read from the title of the referenced document. If that isn’t what you want, you can specify an explicit title and target using a similar syntax to reST hyperlinks (and Sphinx’s cross-referencing syntax). This looks like:

.. toctree::

   intro
   All about strings <strings>
   datatypes

The second line above will link to the strings document, but will use the title “All about strings” instead of the title of the strings document.

You can also add external links, by giving an HTTP URL instead of a document name.

Section numbering

If you want to have section numbers even in HTML output, give the toplevel toctree a numbered option. For example:

.. toctree::
   :numbered:

   foo
   bar

Numbering then starts at the heading of foo. Sub-toctrees are automatically numbered (don’t give the numbered flag to those).

Numbering up to a specific depth is also possible, by giving the depth as a numeric argument to numbered.

Additional options

If you want only the titles of documents in the tree to show up, not other headings of the same level, you can use the titlesonly option:

.. toctree::
   :titlesonly:

   foo
   bar

You can use “globbing” in toctree directives, by giving the glob flag option. All entries are then matched against the list of available documents, and matches are inserted into the list alphabetically. Example:

.. toctree::
   :glob:

   intro*
   recipe/*
   *

This includes first all documents whose names start with intro, then all documents in the recipe folder, then all remaining documents (except the one containing the directive, of course.) [2]

The special entry name self stands for the document containing the toctree directive. This is useful if you want to generate a “sitemap” from the toctree.

You can also give a “hidden” option to the directive, like this:

.. toctree::
   :hidden:

   doc_1
   doc_2

This will still notify Sphinx of the document hierarchy, but not insert links into the document at the location of the directive – this makes sense if you intend to insert these links yourself, in a different style, or in the HTML sidebar.

In cases where you want to have only one top-level toctree and hide all other lower level toctrees you can add the “includehidden” option to the top-level toctree entry:

.. toctree::
   :includehidden:

   doc_1
   doc_2

All other toctree entries can then be eliminated by the “hidden” option.

In the end, all documents in the source directory (or subdirectories) must occur in some 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.

Use exclude_patterns to explicitly exclude documents or directories from building completely. Use the “orphan” metadata to let a document be built, but notify Sphinx that it is not reachable via a toctree.

The “master document” (selected by master_doc) is the “root” of the TOC tree hierarchy. It can be used as the documentation’s main page, or as a “full table of contents” if you don’t give a maxdepth option.

Changed in version 0.3: Added “globbing” option.

Changed in version 0.6: Added “numbered” and “hidden” options as well as external links and support for “self” references.

Changed in version 1.0: Added “titlesonly” option.

Changed in version 1.1: Added numeric argument to “numbered”.

Changed in version 1.2: Added “includehidden” option.

Special names

Sphinx reserves some document names for its own use; you should not try to create documents with these names – it will cause problems.

The special document names (and pages generated for them) are:

• genindex, modindex, search

  These are used for the general index, the Python module index, and the search page, respectively.

  The general index is populated with entries from modules, all index-generating object descriptions, and from index directives.

  The Python module index contains one entry per py:module directive.

  The search page contains a form that uses the generated JSON search index and JavaScript to full-text search the generated documents for search words; it should work on every major browser that supports modern JavaScript.

• every name beginning with _

  Though only few such names are currently used by Sphinx, you should not create documents or document-containing directories with such names. (Using _ as a prefix for a custom template directory is fine.)

Warning

Be careful with unusual characters in filenames. Some formats may interpret these characters in unexpected ways:

• Do not user the colon : for HTML based formats. Links to other parts may not work.
• Do not use the plus + for the ePub format. Some resources may not be found.

Footnotes

[1]	The maxdepth option does not apply to the LaTeX writer, where the whole table of contents will always be presented at the begin of the document, and its depth is controlled by the tocdepth counter, which you can reset in your latex_preamble config value using e.g. \setcounter{tocdepth}{2}.

[2]	A note on available globbing syntax: you can use the standard shell constructs *, ?, [...] and [!...] with the feature that these all don’t match slashes. A double star ** can be used to match any sequence of characters including slashes.