Restructure documentation for the toctree directive (#12725)

Structure the options using `.. rst:directive:option::` and adapt some descriptions where suitable.

Co-authored-by: Adam Turner <[email protected]>

Author: timhoffm

doc/usage/restructuredtext/directives.rst

@@ -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
 ^^^^^^^^^^^^^