mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
243 lines
8.1 KiB
ReStructuredText
243 lines
8.1 KiB
ReStructuredText
.. highlight:: rst
|
|
.. _toctree-directive:
|
|
|
|
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.
|
|
|
|
.. note::
|
|
|
|
Simple "inclusion" of one file in another can be done with the
|
|
:dudir:`include` directive.
|
|
|
|
.. rst: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. [#]_
|
|
|
|
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 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 :rst:dir:`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 :ref:`cross-referencing syntax <xref-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**
|
|
|
|
You can use ``caption`` option to provide a toctree caption and you can use
|
|
``name`` option to provide implicit target name that can be referenced by
|
|
using :rst:role:`ref`::
|
|
|
|
.. toctree::
|
|
:caption: Table of Contents
|
|
:name: mastertoc
|
|
|
|
foo
|
|
|
|
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.) [#]_
|
|
|
|
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 use the ``reversed`` flag option to reverse the order of the entries
|
|
in the list. This can be useful when using the ``glob`` flag option to
|
|
reverse the ordering of the files. Example::
|
|
|
|
.. toctree::
|
|
:glob:
|
|
:reversed:
|
|
|
|
recipe/*
|
|
|
|
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 :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:`exclude_patterns` to explicitly exclude documents or
|
|
directories from building completely. Use :ref:`the "orphan" metadata
|
|
<metadata>` to let a document be built, but notify Sphinx that it is not
|
|
reachable via a toctree.
|
|
|
|
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.
|
|
|
|
.. versionchanged:: 0.6
|
|
Added "numbered" and "hidden" options as well as external links and
|
|
support for "self" references.
|
|
|
|
.. versionchanged:: 1.0
|
|
Added "titlesonly" option.
|
|
|
|
.. versionchanged:: 1.1
|
|
Added numeric argument to "numbered".
|
|
|
|
.. versionchanged:: 1.2
|
|
Added "includehidden" option.
|
|
|
|
.. versionchanged:: 1.3
|
|
Added "caption" and "name" 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
|
|
: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.)
|
|
|
|
.. warning::
|
|
|
|
Be careful with unusual characters in filenames. Some formats may interpret
|
|
these characters in unexpected ways:
|
|
|
|
* Do not use 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.
|
|
|
|
.. rubric:: Footnotes
|
|
|
|
.. [#] The LaTeX writer only refers the ``maxdepth`` option of first toctree
|
|
directive in the document.
|
|
|
|
.. [#] 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.
|