Directives — Sphinx documentation

As previously discussed, a directive is a generic block of explicit markup. While Docutils provides a number of directives, Sphinx provides many more and uses directives as one of the primary extension mechanisms.
See Domains for roles added by domains.
Refer to the reStructuredText Primer for an overview of the directives provided by Docutils.
Since reStructuredText 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 include directive.
To create table of contents for current document (.rst file), use the standard reStructuredText contents directive.
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. [1]
The representation of “TOC tree” is changed in each output format. The builders that output multiple files (e.g. HTML) treat it as a collection of hyperlinks. On the other hand, the builders that output a single file (e.g. LaTeX, man page, etc.) replace it with the content of the documents on the TOC tree.
Consider this example (taken from the Python docs’ library reference index):
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.
Document titles in the 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 reStructuredText hyperlinks (and Sphinx’s cross-referencing syntax). This looks like:
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.
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.
In the end, all documents in the 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 exclude_patterns to explicitly exclude documents or directories from building completely. Use the “orphan” metadata to let a document be built, but notify Sphinx that it is not reachable via a toctree.
The “root document” (selected by root_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.
Changed in version 0.6: Added support for external links and “self” references.
Assign class attributes. This is a common option. For example:
Added in version 7.4.
An implicit target name that can be referenced using ref. This is a common option. For example:
Added in version 1.3.
Add a caption to the toctree. For example:
Added in version 1.3.
If you want to have section numbers even in HTML output, add the :numbered: option to the top-level toctree. For example:
Section 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.
Added in version 0.6.
Changed in version 1.1: Added the numeric depth argument.
Only list document titles, not other headings of the same level. For example:
Added in version 1.0.
Parse glob wildcards in toctree entries. All entries are matched against the list of available documents, and matches are inserted into the list alphabetically. For 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.) [2]
Added in version 0.3.
Reverse the order of the entries in the list. This is particularly useful when using the :glob: option.
Added in version 1.5.
A hidden toctree only defines the document hierarchy. It will not insert links into the document at the location of the directive.
This makes sense if you have other means of navigation, e.g. through manual links, HTML sidebar navigation, or if you use the :includehidden: option on the top-level toctree.