export:puml
Table of contents
- Introduction
- Drawing the database models
- Drawing the feature dependencies
- Drawing the Docker topology
- Rendering an image
- Refreshing stale contracts
- Reference
- See also
Introduction
export:puml draws your product as a PlantUML diagram. By default it draws the feature model, and it can also draw the database models, the feature dependencies or the Docker topology. It needs a selected product (SPLENT_APP).
splent export:puml
đź“– Reading UVL model: /workspace/.splent_cache/spls/sample_splent_spl@v4/sample_splent_spl.uvl
đź“‹ Loaded contracts for 9/12 features.
âś… PlantUML source written: /workspace/my_first_app/exports/puml/my_first_app.puml
Every feature of the UVL model appears as <<mandatory>>, <<optional>>, <<alternative>> or <<or>>. Each feature your product has also shows its contract, from models and routes to env vars and required features. A plain A => B constraint becomes a requires arrow.
Drawing the database models
splent export:puml --classes
It reads the models.py of each feature your product has, one package per feature. Attributes show their type, <<PK>>, <<unique>> and ? when nullable. A foreign key is "1" -- "1" for a unique column and "1" -- "*" otherwise.
A refiner that extends a model with a mixin has the mixin merged into its target, so you see the composed model.
Drawing the feature dependencies
splent export:puml --deps
Every feature of the model is a node, dark blue when mandatory, light blue when optional, orange in an alternative group and green in an or group. Each plain A => B constraint is a requires arrow.
Drawing the Docker topology
splent export:puml --deployment
It reads the dev Compose file of your product and of each feature that ships one, plus the CLI’s own. You get every container with its image, ports, depends_on links and named volumes.
Rendering an image
splent export:puml --classes --svg
splent export:puml --deps --png --pdf
The .puml file is always written. --svg, --png and --pdf also render it, and you can combine them. The CLI container has the PlantUML and rsvg-convert they need.
To write somewhere else, give -o a path without the extension.
splent export:puml --classes -o docs/diagrams/models --pdf
Refreshing stale contracts
A contract is stale when a .py or .html file in an editable feature’s src/, outside tests/ and migrations/, is newer than its pyproject.toml. The command lists those features and asks Update stale contracts now?.
Yes rewrites them as feature:contract --write does. No draws from them as they are. With no input to read, as in CI, it prints Run: splent feature:contract <feature> --write and goes on.
Reference
Options
| Option | Description |
|---|---|
--classes |
UML class diagram of the models |
--deps |
Dependency graph of the features |
--deployment |
Docker deployment diagram |
--svg, --png, --pdf |
Also render the diagram in this format |
-o, --output PATH |
Output path, without extension. Default <product>/exports/puml/<file> |
The three modes exclude each other. Two at once is a usage error (exit 2).
| Mode | File |
|---|---|
| Feature model | <product>.puml |
--classes |
<product>_classes.puml |
--deps |
<product>_deps.puml |
--deployment |
<product>_deployment.puml |
Where the model comes from
It resolves [tool.splent].spl as every command does, from the working copy splent_spl_<name>/, then .splent_cache/spls/, then UVLHub with the DOI under [tool.splent.spl_model]. A product that names no SPL can point at a file in <product>/uvl/ with [tool.splent.uvl].file.
Errors
All of these exit 1.
| Message | What to do |
|---|---|
| The places it looked for the model | Run splent spl:fetch <name> when a DOI is recorded |
❌ No UVL file found. |
Set [tool.splent].spl |
❌ PlantUML not found. |
Rebuild the CLI container with make setup-rebuild |
❌ PlantUML failed to render diagram. |
PlantUML’s output below it points at the faulty line of the .puml file |
❌ Could not export PDF. or PNG. |
Read rsvg-convert’s output below it. The other format still renders |
A render over 10 minutes is stopped.
See also
product:validatechecks the UVL model and the conflicts between features.feature:contractinfers and writes a feature’s contract.