Toctree and the hierarchical structure of a manual¶
You can define what should be included in the menu with the
.. toctree:: directive.
.rst files that are included in a toctree, are included in the menu.
The toctree directive can also be used to display a table of contents on current page (if :hidden: is not added in toctree).
The first headline of an .rst file is its "doctitle". That is the document's title property. The title and the following headlines are used for cross-references and appear in menus and table of contents.
General rules for using
Each .rst file should have a doctitle, for example:
========== Some Title ==========
Do not use any additional headlines in the file if it contains a
Note: What we call "headlines" here is called "sections" in reST-jargon, see Headlines and sections.
How it works¶
2017-02-13 by Martin Bless
TYPO3 documentation usually starts with the file
The text may go into more than one textfile and these can be "pulled in" and
referenced by the
.. toctree::directive creates a sublevel of headlines in the menu.
The sublevel refers to the current level.
Sometimes you don't get what you expect:
================ My Documentation ================ Introduction ============ This project does something very useful ... See the individual chapters. .. toctree:: Chapter-1 Chapter-2 Chapter-3
The example feels very natural. We are thinking of the introduction followed by the single chapters. Unfortunately we get something different. The chapters will all be a subpart of Introduction and not at the same level. It is exactly what the Sphinx documentation states and there is no easy way to "tweak" this behavior.
Use these rules of thumb:
All or nothing: Pull in all content of a given level via
toctreeor don't use
Or, in other words: Do not use a headline ("section") in a document before a
.. toctree::directive unless you really want to place the pulled in documents at a sublevel of that section.
Here is how we can fix the example: Move the introduction to an extra file and pull it in just like the others.
================ My Documentation ================ You can have text here. But don't introduce headlines, if you want to have the pulled in files at the same level. .. toctree:: Introduction Chapter-1 Chapter-2 Chapter-3
Now the document titles (not shown here) of the files
Chapter-3will all be at the sublevel of
My Documentationin the menu.