What is UMLet

In software development, UML (Unified Modeling Language) diagrams are commonly used to better understand the structure of a system and the relationships between different parts of an application. These diagrams help development teams visualize the architecture and behavior of a system before implementation or during the documentation process.

UMLet is a simple and lightweight tool for creating UML diagrams. Unlike some modeling tools that have a high level of complexity, UMLet focuses on speed and simplicity, allowing users to quickly create and edit diagrams

What is Sphinx

Sphinx is a documentation generator tool that is used to create documentation from text-based source files.

 How does Sphinx work

The Source directory is where the main documentation files are stored. It contains text files with the .rst format, project configuration files such as conf.py, images, and other input files such as diagrams. These files are created and edited by the author.

The Build directory stores the output generated by Sphinx. When Sphinx builds the project, it processes the content from the Source directory and places generated outputs such as HTML pages, PDF files, and generated assets like SVG files in this directory.

After installing Sphinx and creating a project using the `sphinx-quickstart` command, an initial project structure is generated.

The project can then be opened with an editor such as VS Code, where required files such as `.rst` documents and the `conf.py` configuration file can be edited. At this stage, the content and structure of the documentation are created

Whenever needed, the project can be built by running a command such as `make html`. Sphinx processes the written source files and converts them into HTML pages that can be viewed in a web browser

What is Sphinx-Umlet

If we want to include diagrams in our documentation, we cannot directly use UMLet files as regular text content inside Sphinx. To use diagrams created with UMLet in Sphinx documentation, an extension is required.

Sphinx-Umlet provides a connection between UMLet diagrams and Sphinx. This extension takes UMLet diagram files with the .uxf format and, during the Sphinx build process, converts them into a web-compatible format such as SVG.

As a result, UML diagrams created in UMLet can be displayed alongside other documentation content in the generated HTML output

How Sphinx-Umlet works

First, a diagram is designed in the UMLet environment and saved in the .uxf format. Then, this file is placed inside the Sphinx project. After enabling the sphinx-umlet extension in the conf.py configuration file, the extension detects the .uxf file during the Sphinx build process and converts it into a documentation-friendly format such as SVG

Adding Extension in Sphinx

To add the sphinx-umlet extension, we first need to obtain the source code of the extension.

git clone [email protected]:odoonix/sphinx-umlet.git

Inside the source directory of the Sphinx project, create a folder named _extension.

Then, place the Extension package (the folder that contains the __init__.py file). This folder is the main Python package of the Extension and should be placed inside source/_extension

Finally, enable the Extension in the Sphinx configuration file, conf.py 

extensions = [
   , "_extension.sphinx_umlet"
]

After this step, Sphinx recognizes the Extension during the project build process and enables the ability to use UMLet diagrams.

To use UMLet files (.uxf) in the Sphinx project, we create a folder named model inside the source/ directory to store the diagrams. The .uxf file, which represents the UMLet diagram, is placed inside this folder.

To display the diagram in the documentation, we use the Extension's custom directive in the index.rst file:

uml:: model/file
   	​	​  : alt: Test UML Diagram    
   :align: center    
   :width: 100%    

Any changes made to the .rst files require rebuilding the project.

The build command should be executed from the root directory of the Sphinx project

make html

Sphinx processes the RST files, converts the UMLet diagrams, and generates the HTML output.

If you encounter the following error while running this command

No module named '_extension'

To resolve this issue, add the source directory path to the Python path at the beginning of conf.py

import os
import sys

sys.path.insert(0, os.path.abspath("."))

This allows Sphinx to locate and import the _extension package.

After the build process is completed, the generated SVG file is referenced in the final HTML output through an image tag. By opening the generated HTML page in a web browser, the UMLet diagram can be viewed as part of the documentation

Customizing the Appearance

Since the final output is an HTML image element, its appearance can be customized using CSS.

Custom CSS files can be placed inside

source/_static/

Then, the static folder must be added to the Sphinx configuration file conf.py

html_static_path = ["_static"]

After that, custom styles can be defined in the CSS file for the classes related to the image or UML diagram

Extension File Responsibilities

__init__.py  : Introduces the Extension to Sphinx and registers Nodes, Directives, and Events

asset.py     : Defines the custom Node type UMLetAsset

directive.py : Processes the UML directive in RST and inserts UMLetAsset into the Document Tree

events.py    : Manages the Build process and controls the conversion stage

renderer.py  : Converts .uxf files into .svg files

html.py      : Converts UMLetAsset into HTML output and displays the Diagram

Summary / General Guide

To use UMLet diagrams in Sphinx documentation

. Install Sphinx and create a project.

. Add the sphinx-umlet extension.

. Place .uxf files inside the source directory.

. Use the .. uml:: directive in RST files.

. Run make html to generate the documentation.

. Customize the appearance using CSS if required.

With this workflow, UMLet diagrams can be integrated into Sphinx documentation as native asset