Sphinx error: The … directive is empty; content required

Did you Sphinx documentation project has failed with the error The … directive is empty; content required? This guide provides an explanation and solution to resolve the issue.

Symptom

Sphinx build failed with the error similar to:

WARNING: The "list-table" directive is empty; content required.

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

Directive is an block that does something special with a passed text. May directives require content, e.g. list-table::, or topic::. The warning above means you forgot the directive content or isn’t properly indented.

Example

.. topic:: Topic Title

Subsequent indented lines comprise
the body of the topic, and are
interpreted as body elements.

Solution

Directive content needs to be properly indented at the column where directive name starts (here at the column 3):

.. topic:: Topic Title

   Subsequent indented lines comprise
   the body of the topic, and are
   interpreted as body elements.