Commit 06dd99e

.. highlight:: rest

Document names

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.

.. directive:: toctree

This directive inserts a "TOC tree" at the current location, using the

individual TOCs (including "sub-TOC trees") of the files given in the

directive body. A numeric ``maxdepth`` option may be given to indicate the

depth of the tree; by default, all levels are included.

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

This accomplishes two things:

* Tables of contents from all those files are inserted, with a maximum depth

of two, that means one nested heading. ``toctree`` directives in those

files are also taken into account.

* Sphinx knows that the relative order of the files ``intro.rst``,

``strings.rst`` 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 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. Use :confval:`unused_documents` to explicitly exclude

documents from this check.

The "master file" (selected by :confval:`master_file`) 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.