The main purpose of toctree is to list document names that will make up the table of contents of the whole documentation. The order of document names here, will be the order in the ToC and used also for “next” and “prev” navigation links.

Document name is basically a file path without extension. For example, file element/toctree.rst is document name element/toctree. (Use forward slash / even on Windows.)

Almost every time, you put toctree in a root document usually called index(.rst).

Toctree expect relative or absolute document names.

Relative document names are relative to the current document (containing toctree). Relative document names are those which not begin with /. For example, transition is transition.rst in the current folder, or collection/parts is collection/parts.rst, etc.

.. toctree::

   ../europe
   czech
   czech/prague
   germany

On the opposite, absolute document names denoted with initial / are relative to the source directory (folder containing conf.py), i.e. project root.

You can combine relative and absolute document names in the single toctree:

.. toctree::
   
   introduction
   /europe
   /europe/czech
   /europe/germany

In the bigger documentations, you have a tons of files. It is possible, but impractical, to list every document in the single toctree like this:

.. toctree::
   
   asia/japan
   asia/south-korea
   ...

Better is to include only “top” documents and have another toctree in them. For example, imagine these file structure:

/europe
    czech.rst
    germany.rst
    ...
/asia
    japan.rst
    south-korea.rst
index.rst
europe.rst
asia.rst
...

We want to make up a ToC structure continent → country. Entry document index contains:

Welcome to our tourist guide!
#############################

.. toctree::

   europe
   asia

Top-level document europe contains:

Europe`s tourist guide
######################

.. toctree::
   
   czech
   german

and, something very similar in asia. In the result, you build this table of contents:

• Europe

  • Czech Republic

  • Germany

• Asia

  • Japan

  • South Korea

See the above illustrated:

In the end, all documents must appear in some toctree or be included with include:: directive. Actually, a document can be included in more toctree directives.

If it is not, a reader can’t reach the document via normal navigation (no links will refer to the document), thus you will get WARNING: document isn't included in any toctree.

A document that you want to build (e.g. make a HTML from it), but “hide” it from table of contents, must be marked with :orphan: on the first line. It also suppress WARNING: document isn't included in any toctree.

:orphan:

Excluded document
#################

Is not part of any toctree.

To open the excluded document in the output folder, you need to enter its path (or URL). For example, if previous document name is etc/excluded, for HTML the output file will be etc/excluded.html.

If you want section numbering like “1. Europe”, “1.2 Germany”, “1.2.1 Berlin”, use :numbered: option to tocree directive. It starts numbering on the toctree and its sub-toctrees. To auto-number all sections, use the option on the toctree in root document.

By default, at the place where is the toctree is used, also resulting table of contents is printed (as in all above examples). Many Sphinx themes (skins changing HTML look) has a sidebar with the global ToC. In this case, it is useless to have ToC again in the main page block. You can hide it with the toctree directive option :hidden:.