How can I include a plantuml file in reStructuredText with Sphinx

Question

I have a plantuml file composite.puml with the following content:

package composite {
  class Letter {
    + __init__(char: str)
    # print_this_before()
  }

And I try to include this in a reStructuredText document (which uses the sphinxcontrib.plantuml plugin):

.. uml::
    .. include:: composite.puml

But this throws an exception when running make html

Running Sphinx v2.4.1
/Users/jve23941
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 10 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] structural_patterns/composite
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:51: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:52: WARNING: Definition list ends without a blank line; unexpected unindent.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:54: WARNING: Unexpected indentation.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:57: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:59: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:61: WARNING: Unexpected indentation.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:63: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:65: WARNING: Unexpected indentation.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:65: WARNING: Inline emphasis start-string without end-string.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:66: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:67: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:69: WARNING: Unexpected indentation.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:69: WARNING: Inline emphasis start-string without end-string.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:70: WARNING: Inline emphasis start-string without end-string.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:71: WARNING: Bullet list ends without a blank line; unexpected unindent.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:72: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:73: WARNING: Definition list ends without a blank line; unexpected unindent.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:73: WARNING: Inline substitution_reference start-string without end-string.
/Users/jve23941/workspace/python-design-patterns/docs/structural_patterns/composite.rst:73: WARNING: Undefined substitution referenced: "> LetterComposite Sentence --".
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] structural_patterns/index
generating indices...  genindex py-modindexdone
highlighting module code... [100%] python_design_patterns.composite
writing additional pages...  search/Users/jve23941/workspace/python-design-patterns/.venv/lib/python3.8/site-packages/sphinx_rtd_theme/search.html:21: RemovedInSphinx30Warning: To modify script_files in the theme is deprecated. Please insert a <script> tag directly in your theme instead.
  {% endblock %}
done
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 19 warnings.

The HTML pages are in _build/html.

I think this is because Sphinx cannot handle the content I put in the plantuml file.

How can I include the plantuml file so it works

Answer 1

Shouldn't the inclusion of the external file be like the following instead?

.. uml:: composite.puml