merge with stable

1 files changed, 6 insertions, 3 deletions

diff --git a/doc/markup/toctree.rst b/doc/markup/toctree.rst
index fdecc37df..1d5d667ae 100644
--- a/doc/markup/toctree.rst
+++ b/doc/markup/toctree.rst
@@ -141,9 +141,12 @@ tables of contents.  The ``toctree`` directive is the central element.
    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.  Use :ref:`metadata` to remove the
-   warning, and :confval:`exclude_patterns` to explicitly exclude documents or
-   directories from building.
+   be reachable through standard navigation.
+
+   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.
 
    The "master document" (selected by :confval:`master_doc`) is the "root" of
    the TOC tree hierarchy.  It can be used as the documentation's main page, or