mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
59 lines
2.0 KiB
ReStructuredText
59 lines
2.0 KiB
ReStructuredText
.. highlight:: rest
|
|
|
|
.. _concepts:
|
|
|
|
Sphinx concepts
|
|
===============
|
|
|
|
Document names
|
|
--------------
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
.. 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)::
|
|
|
|
.. toctree::
|
|
:maxdepth: 2
|
|
|
|
intro.rst
|
|
strings.rst
|
|
datatypes.rst
|
|
numeric.rst
|
|
(many more files listed here)
|
|
|
|
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.
|