TechWriter at work blog

Living and writing documentation at Documatt, small team of programmers that write documentation too.

---

Document isn’t included in any toctree

Symptoms

Sphinx build failed with the error similar to:

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

Reasons

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: