Sphinx error: Document isn’t included in any toctree#

Did you Sphinx documentation project has failed with the error Document isn’t included in any toctree? This guide provides an explanation and solution to resolve the issue.

Symptom#

Sphinx build failed with the error similar to:

third.rst: WARNING: document isn't included in any toctree

Worry-free Sphinx?

Documatt app is a Sphinx-based tool which hides its complexity with free hosting for your books and docs.

Try free 14 day trial Watch the demo

Reason#

All source document files found by Sphinx must be part of table of contents. If Sphinx finds document that isn’t included in any toctree, it warns about it. Sphinx builds it, but readers needs to know exact URL or path to the document to see it, because they can’t reach the document through normal ToC navigation.

Example#

Your Sphinx project contains the following source files:

index.rst
second.rst
third.rst

Index’s toctree includes first and second documents, but omit third document:

Welcome!
========

Lorem ipsum.

.. toctree::

   first
   second

Solution#

If it is your intention to exclude document from toctrees, use special orphan metadata field.

:orphan:

Marked as orphan
==================

I'm also orphan document that isn't included in any toctree, but marked as :orphan:

Sphinx Errors parade