Skip to content

Commit

Permalink
Restructure documentation for the toctree directive (#12725)
Browse files Browse the repository at this point in the history 
Structure the options using `.. rst:directive:option::` and adapt some descriptions where suitable.

Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
  • Loading branch information
@timhoffm @AA-Turner
timhoffm and AA-Turner authored Aug 11, 2024
1 parent 3bab324 commit 4cf8f7a
Showing 1 changed file with 110 additions and 92 deletions.
202 changes: 110 additions & 92 deletions doc/usage/restructuredtext/directives.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -96,138 +96,156 @@ The ``toctree`` directive is the central element.
You can also add external links, by giving an HTTP URL instead of a document
name.

**Section numbering**
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.

If you want to have section numbers even in HTML output, give the
**toplevel** toctree a ``numbered`` option. For example::
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.

.. toctree::
:numbered:
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.

foo
bar
The "root document" (selected by :confval:`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.

Numbering then starts at the heading of ``foo``. Sub-toctrees are
automatically numbered (don't give the ``numbered`` flag to those).
.. versionchanged:: 0.6
Added support for external links and "self" references.

Numbering up to a specific depth is also possible, by giving the depth as a
numeric argument to ``numbered``.
.. rubric:: options

**Additional options**
.. rst:directive:option:: class: class names
:type: a list of class names, separated by spaces
You can use the ``caption`` option to provide a toctree caption and you can
use the ``name`` option to provide an implicit target name that can be
referenced by using :rst:role:`ref`::
Assign `class attributes`_.
This is a :dudir:`common option <common-options>`.
For example::
.. toctree::
:caption: Table of Contents
:name: mastertoc
.. toctree::
:class: custom-toc
foo
.. _class attributes: https://docutils.sourceforge.io/docs/ref/doctree.html#classes
As with :dudir:`most directives <common-options>`,
you can use the ``class`` option to assign `class attributes`_::
.. versionadded:: 7.4
.. toctree::
:class: custom-toc
.. rst:directive:option:: name: label
:type: text
.. _class attributes: https://docutils.sourceforge.io/docs/ref/doctree.html#classes
An implicit target name that can be referenced using :rst:role:`ref`.
This is a :dudir:`common option <common-options>`.
For example::
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::
:name: mastertoc
.. toctree::
:titlesonly:
foo
foo
bar
.. versionadded:: 1.3
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::
.. rst:directive:option:: caption
:type: text
.. toctree::
:glob:
Add a caption to the toctree.
For example::
intro*
recipe/*
*
.. toctree::
:caption: Table of Contents
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.) [#]_
foo
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.
.. versionadded:: 1.3
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::
.. rst:directive:option:: numbered
numbered: depth
.. toctree::
:glob:
:reversed:
If you want to have section numbers even in HTML output,
add the ``:numbered:`` option to the *top-level* toctree.
For example::
recipe/*
.. toctree::
:numbered:
You can also give a "hidden" option to the directive, like this::
foo
bar
.. toctree::
:hidden:
Section numbering then starts at the heading of ``foo``.
Sub-toctrees are automatically numbered
(don't give the ``numbered`` flag to those).
doc_1
doc_2
Numbering up to a specific depth is also possible,
by giving the depth as a numeric argument to ``numbered``.
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.
.. versionadded:: 0.6
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::
.. versionchanged:: 1.1
Added the numeric *depth* argument.
.. toctree::
:includehidden:
.. rst:directive:option:: titlesonly
doc_1
doc_2
Only list document titles, not other headings of the same level.
For example::
All other toctree entries can then be eliminated by the "hidden" option.
.. toctree::
:titlesonly:
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.
foo
bar
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.
.. versionadded:: 1.0
The "root document" (selected by :confval:`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.
.. rst:directive:option:: glob
.. versionchanged:: 0.3
Added "globbing" option.
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::
.. versionchanged:: 0.6
Added "numbered" and "hidden" options as well as external links and
support for "self" references.
.. toctree::
:glob:
.. versionchanged:: 1.0
Added "titlesonly" option.
intro*
recipe/*
*
.. versionchanged:: 1.1
Added numeric argument to "numbered".
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.) [#]_
.. versionchanged:: 1.2
Added "includehidden" option.
.. versionadded:: 0.3
.. rst:directive:option:: reversed
Reverse the order of the entries in the list.
This is particularly useful when using the ``:glob:`` option.
.. versionadded:: 1.5
.. rst:directive:option:: hidden
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.
.. versionadded:: 0.6
.. rst:directive:option:: includehidden
If you want one global table of contents showing the complete document structure,
you can add the ``:includehidden:`` option to the *top-level* toctree directive.
All other toctrees on child pages can then be made invisible
with the ``:hidden:`` option.
The top-level toctree with ``:includehidden:`` will then include their entries.
.. versionadded:: 1.2
.. versionchanged:: 1.3
Added "caption" and "name" option.
Special names
^^^^^^^^^^^^^
Expand Down

0 comments on commit 4cf8f7a

Please sign in to comment.