Embed a plantuml diagram somewhere in a docstring (with the Sphinx plantuml extension)

Question

I installed the sphinxcontrib-plantuml extension which works fine if I run the HTML builder e.g. with following testmodule.rst file for a corresponding testmodule.py file:

testmodule module
=================

.. automodule:: testmodule
    :members:
    :undoc-members:
    :show-inheritance:

.. uml::
   
   Alice -> Bob: Hi!
   Alice <- Bob: How are you?

This adds the UML diagram at the very end of the document. Unfortunately I didn't find out how to embed a UML diagram anywhere in the documentation e.g. somewhere in the middle of a methods docstring block.

Does anyone know how to do that?

Answer 1

Adding the UML diagram directly in the docstring section didn't work for me. But following worked for me:

1. Put plantuml code in separate file e.g. diagram.uml:

@startuml
   Alice -> Bob: Hi!
   Alice <- Bob: How are you?
@enduml

2. Add the plantuml directive with the filename at the desired place in the docstring. E.g.:

def example():
    """
    some text

    .. uml:: diagram.uml

    some more text 
    """
    ...