Error in “xyz” directive: no content permitted

Symptoms

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

Reasons

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.