python-sphinxrestructuredtextplantumlcross-reference

How to Cross-Reference Plantuml Diagram in Sphinx

I am writing some documentation in Sphinx and cannot figure out how to reference a plantuml diagram in text.

Using the numref role I can reference figures via a label, e.g., :numref:`diag`. In text the figure is automatically enumerated in order and the reference to it is rendered like Fig. 1:

.. _diag:

.. figure:: /img/diagram.png
   :align: center

   Figure description

I want to have the same behavior with plantuml diagrams and avoid saving exported plantuml image files in my repository. Example:

.. _diag:

.. uml:: ../plantuml/diag.puml
   :align: center

During building via make html this leads to the error WARNING: undefined label: 'diag'.

Is there maybe some way or a nice workaround to achieve this?

Solution

  • I have finally found a solution. It is necessary to add a caption field like this:

    .. _diag:

.. uml:: ../plantuml/diag.puml
   :align: center
   :caption: Some caption for the diagram

    When that is done, the diagram can be referenced like figures via :numref:`diag`.

    For more information on the plantuml extension I can recommend the GitHub website.