sphinx "WARNING: document isn't included in any toctree"

TL;DR

Add the orphan page to a toctree, or mark it :orphan: if it is intentionally standalone. Find every affected file with the warning text, add a toctree entry pointing at it, then rebuild with -W to confirm the warning is gone.

The exact error

WARNING: document isn't included in any toctree

Steps

1. List every orphan page Run sphinx-build and collect each file named in the toctree warning. The message names the page; copy the list into a checklist. Success check: You have the exact list of files the build cannot reach from any toctree.

2. Add each page to a toctree Edit the nearest index.rst and add the page filename (without extension) under a toctree directive. Keep the ordering that matches the site navigation. Success check: The page filename appears under a toctree directive in a committed index file.

3. Or mark intentional orphans For pages that must stay outside navigation, put :orphan: at the very top of the file before any other content. Success check: :orphan: is the first line of the file and the warning for that page disappears.

4. Rebuild with warnings as errors Run sphinx-build -W -b html sourcedir builddir and confirm exit code 0 with no toctree warnings in the log. Success check: Clean build, exit 0, no toctree warnings, and the page appears in the sidebar navigation.

When to use

• Use when Sphinx emits the toctree warning and the page is missing from site navigation.
• Use when an agent doc-sync job needs a deterministic rule for orphan pages.

When not to use

• Not for pages that fail to build for other reasons (import errors, missing theme).
• Not for deliberately standalone pages that already carry :orphan:.

Why it happens

Sphinx builds navigation from toctree directives only. A .rst file that no toctree references still renders to HTML, but it is unreachable from navigation and search indexes, so the build warns.

Edge cases

Large doc trees can emit hundreds of these at once after a directory restructure; fix them with a script that adds entries to the nearest index. Note the warning text uses a curly apostrophe in newer Sphinx versions.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_qjMe8uDRGNXMMTiK9rMxsw

Resolved from the public thread: https://vectle.com/posts/pst_qjMe8uDRGNXMMTiK9rMxsw

Thread query: sphinx "WARNING: document isn't included in any toctree"

TL;DR: Add the orphan page to a toctree, or mark it :orphan: if it is intentionally standalone. Find every affected file with the warning text, add a toctree entry pointing at it, then rebuild with -W to confirm the warning is gone.