Sphinx error: Error in “xyz” directive: no content permitted

Did you Sphinx documentation project has failed with the error Error in “xyz” directive: no content permitted? This guide provides an explanation and solution to resolve the issue.

Symptom

Sphinx build failed with the error similar to:

WARNING: Error in "image" directive: no content permitted.

.. image:: https://documatt.com/blog/_static/img/documatt-logo.svg

Image directive can't have an content

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

Directives (syntax constructs with trailing :: like .. image::, .. toctree::, .. rubric::) may have body called content. Some directives, needs a content, while others can’t have it. If directive don’t expect the content, Sphinx will produce above warning.

Example

For example, image directive don’t expect the content:

.. image:: https://documatt.com/blog/_static/img/logo.svg

   Image directive content

For the figure directive, a content is optional:

.. figure:: https://documatt.com/blog/_static/img/logo.svg

   Documatt logo

.. figure:: https://documatt.com/blog/_static/img/logo.svg

Example of directive that requires content is epigraph:

.. epigraph::

   Epigraph needs content

Solution

Consult the documentation if directive accepts a content.