Toctree Directives
Every .. toctree:: option and entry form, so the rendered site exercises
each of them.
The toctree below uses an explicit :caption:, an Explicit Title <target>
entry, a self entry pointing back at this page, and an external link — none
of which name a document the way a plain entry does.
Entry forms
Numbering
:numbered: numbers everything it reaches, across document boundaries, and
the numbers appear both here and as prefixes on the target pages' headings.
The third chapter also writes its own .. sectnum::, which this toctree's
numbering overrides entirely — see that page for why.
Numbered chapters
Depth limits
The same two documents again, at :maxdepth: 1 — proving two toctrees in one
document render differently, which they could not before.
:titlesonly: drops the section entries instead of limiting their depth.
Globs and ordering
:glob: expands a pattern against the project's documents, sorted; a *
does not cross a /. :reversed: flips the order after expansion.
Hidden
A :hidden: toctree renders nothing here but still contributes to the
sidebar, the reading order and the section numbering. Its :name: makes it a
reference target: hidden-toc.
orphan.rst is deliberately listed by no toctree, and says so with an
:orphan: field of its own — removing that field is what makes the build
warn about it.