Sphinx substitution with a container

Question

How can I substitute a container directive ? The following doesn't work:

.. |sub| container::

    Some text here

    .. image:: img/some_image.png

    Some other text here

The error message is

WARNING: Substitution definition "sub" empty or invalid.

Answer 1

This is not possible. ReST substitutions apply to inline text (single paragraphs), but a container is a block element.

And if you try

.. |sub| replace:: container::

    Some text here

    .. image:: img/some_image.png

    Some other text here

you will get

ERROR: Error in "replace" directive: may contain a single paragraph only.

You could work around this by putting the container in a separate file and pull it in to the master file using .. include::.