From 4cf8f7a093a9fad4e81f90dce944f3415c55f1e6 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Sun, 11 Aug 2024 17:36:01 +0200 Subject: [PATCH] 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 <9087854+aa-turner@users.noreply.github.com> --- doc/usage/restructuredtext/directives.rst | 202 ++++++++++++---------- 1 file changed, 110 insertions(+), 92 deletions(-) diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index 19079d2cfed..c32d7a1c4e4 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/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 + ` 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 `. + 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 `, - 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 `. + 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 - ` 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 ^^^^^^^^^^^^^