Skip to content

Latest commit

 

History

History
106 lines (66 loc) · 3.67 KB

README.rst

File metadata and controls

106 lines (66 loc) · 3.67 KB
Raw

sphinxcontrib-umlet

Sphinx Extension for effordlessly embedding UMLet diagrams in your Sphinx document.

.. umlet-figure:: some_folder/some_diagram.uxf

It adds the umlet-image and umlet-figure directives. These are equivalent to the standard image and figure directives, but accept the path to a .uxf file and additional options to control exporting of the diagram to a suitable image format.

Attention!

This extension does not work on readthedocs as RTD does not allow packages (e.g. UMLet) to be installed. If you only require diagrams in a single format, you can consider using editable SVGs or PNGs, accessible through UMLet's GUI via File / Export.

This extension is highly influenced by sphinxcontrib-drawio. Many thanks to the creator @modelmat !

Installation

  1. Make sure that UMLet works on your machine. Java runtime in the path is a prerequisite.
  2. Add the UMLet binary to $PATH. See below for more details and alternative solutions.
  3. pip install sphinxcontrib-umlet
  4. In your sphinx conf.py, register it to the extensions to use, such as:
extensions = []
# ...
extensions.append("sphinxcontrib.umlet")
# ...

Usage

The extension can be used through the umlet-image directive. For example:

.. umlet-image:: some_diagram.uxf

There's also a umlet-figure directive that mimics the figure directive:

.. umlet-figure:: some_diagram.uxf

    Some caption

The directives can be configured with option format to control the export of the specific UMLet diagram to a bitmap or vector image. This option controls the output file format of this specific directive, so it overrides the export format commonly used or commonly configured in the conf.py file.

  • Name: :format:
  • Default value: "png"
  • Possible Values: "png", "jpg", "svg" or "pdf"

Additionally, umlet-image accepts all of the options supported by the image directive. These options apply to the image as exported by UMLet. Similarly, umlet-figure accepts all options supported by the figure directive.

Configuration Options

These values are placed in the conf.py of your Sphinx project.

Binary Path

  • Name: umlet_binary_path
  • Default value: None

It is the path including the program's name.

This config option allows for a specific override for the binary location. By default, this chooses the umlet.sh (resp. Umlet.exe) binary accessible in $PATH.

Default Output Format

  • Name: umlet_builder_export_format
  • Default value: {}

This config option controls the default export file format for each Sphinx builder.

It accepts a dictionary mapping builder names to image formats. The builder name should match the name of a Sphinx builder (e.g., "html", "latex"). Accepted values for the export format are "png", "jpg", "svg" and "pdf". If no format is set for a given builder, its preferred image format is used, that is, the first format listed in a builder's supported image types that UMLet is capable of exporting to (eg. SVG for HTML, PDF for LaTeX).