.. highlight:: rest
Since the reST source files can have different extensions (some people like
``.txt``, some like ``.rst`` -- the extension can be configured with
:confval:`source_suffix`) and different OSes have different path separators,
Sphinx abstracts them: all "document names" are relative to the :term:`source
directory`, the extension is stripped, and path separators are converted to
slashes. All values, parameters and suchlike referring to "documents" expect
such a document name.
The TOC tree
.. index:: pair: table of; contents
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 documents given in the
directive body (whose path is relative to the document the directive occurs
in). 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)::
(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.
Document titles in the :dir:`toctree` will be automatically read from the
title of the referenced document. If that isn't what you want, you can give
the specify an explicit title and target using a similar syntax to reST
hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This
All about strings <strings>
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 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::
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.) [#]_
In the end, all documents in the :term:`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 :confval:`unused_documents` to
explicitly exclude documents from building, and :confval:`exclude_dirs` to
exclude whole directories.
The "master document" (selected by :confval:`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.
.. versionchanged:: 0.3
Added "globbing" option.
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 module index, and the search page,
The general index is populated with entries from modules, all index-generating
:ref:`description units <desc-units>`, and from :dir:`index` directives.
The module index contains one entry per :dir:`module` directive.
The search page contains a form that uses the generated JSON search index and
* 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.)
.. rubric:: Footnotes
.. [#] 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
.. [#] 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.