sphinx / doc / markup / toctree.rst

Full commit

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.


Simple "inclusion" of one file in another can be done with the :dudir:`include` directive.

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 :ref:`object descriptions <basic-domain-markup>`, and from :rst:dir:`index` directives.

    The Python module index contains one entry per :rst:dir:`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.)


[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 :confval:`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.