commit 5d4879341ce1353cf00508428c3bff6b42aa6e42
parent fd0e60aa3605734aa4c715ef3d67431d02f691c2
Author: bohdan-potuzhnyi <bohdan.potuzhnyi@gmail.com>
Date: Fri, 24 Jul 2026 13:52:04 +0200
playing around with puml in docs website
Diffstat:
5 files changed, 109 insertions(+), 0 deletions(-)
diff --git a/conf.py b/conf.py
@@ -58,6 +58,7 @@ extensions = [
"sphinx.ext.todo",
"sphinx.ext.graphviz",
"sphinx.ext.imgmath",
+ "sphinxcontrib.plantuml",
"httpdomain.httpdomain",
"myst_parser",
"sphinx_multitoc_numbering",
@@ -67,6 +68,12 @@ extensions = [
imgmath_image_format = 'svg'
imgmath_use_preview = True
+# PlantUML diagrams (``.. uml::``), rendered at build time. Needs a
+# ``plantuml`` command on PATH, provided by the Nix development shell
+# and package.
+plantuml = os.environ.get("PLANTUML", "plantuml")
+plantuml_output_format = "svg"
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
diff --git a/design-documents/098-token-fountains.rst b/design-documents/098-token-fountains.rst
@@ -35,6 +35,19 @@ wallet imports the link, learns which token families are available and
withdraws blind-signed tokens subject to the configured limits. Blind
signatures keep a later use of a token unlinkable from its withdrawal.
+User Flow
+=========
+
+The recipient scans the promotion once. The wallet obtains promotional
+tokens and offers an applicable token later at checkout.
+
+.. uml:: images/098/promotions-user-flow.puml
+ :align: center
+ :width: 90%
+ :caption: Joining and using a token-fountain promotion
+ :alt: Scan the promotion, receive promotional tokens in the wallet, use a
+ token at checkout and receive the discount or benefit.
+
Requirements
============
diff --git a/design-documents/images/098/promotions-user-flow.puml b/design-documents/images/098/promotions-user-flow.puml
@@ -0,0 +1,16 @@
+@startuml promotions-user-flow
+' Recipient-facing flow for DD 98 (Token Fountains for Promotions).
+' Rendered at Sphinx build time via sphinxcontrib.plantuml.
+!include ../../../images/taler-uml-style.iuml
+
+left to right direction
+
+rectangle "Scan the\npromotion" as scan #d3deff
+rectangle "Wallet receives\npromotional tokens" as receive #d3deff
+rectangle "Use a token\nat checkout" as use #d3deff
+rectangle "Receive the\ndiscount or benefit" as benefit #d3deff
+
+scan --> receive
+receive --> use
+use --> benefit
+@enduml
diff --git a/flake.nix b/flake.nix
@@ -26,6 +26,7 @@
pkgs.gnumake
pkgs.texlive.combined.scheme-full
pkgs.gnumake
+ pkgs.plantuml
(pkgs.python3.withPackages (python-pkgs: [
python-pkgs.setuptools
python-pkgs.jinja2
@@ -33,6 +34,7 @@
python-pkgs.sphinx-book-theme
python-pkgs.myst-parser
python-pkgs.sphinxcontrib-httpdomain
+ python-pkgs.sphinxcontrib-plantuml
python-pkgs.sphinx-design
]))
];
@@ -53,6 +55,7 @@
default = pkgs.mkShell {
packages = [
pkgs.gnumake
+ pkgs.plantuml
(pkgs.python3.withPackages (python-pkgs: [
python-pkgs.setuptools
python-pkgs.jinja2
@@ -60,6 +63,7 @@
python-pkgs.sphinx-book-theme
python-pkgs.myst-parser
python-pkgs.sphinxcontrib-httpdomain
+ python-pkgs.sphinxcontrib-plantuml
python-pkgs.sphinx-design
]))
];
diff --git a/images/taler-uml-style.iuml b/images/taler-uml-style.iuml
@@ -0,0 +1,69 @@
+' Shared PlantUML style for diagrams in taler-docs, using the Taler
+' brand palette (see DD 90 "Branding" and DD 66 "Wallet color scheme").
+
+skinparam shadowing false
+skinparam defaultFontName sans-serif
+skinparam ArrowColor #0042b3
+skinparam ArrowFontColor #00134a
+
+skinparam participant {
+ BackgroundColor #d3deff
+ BorderColor #0042b3
+ FontColor #00134a
+}
+
+skinparam actor {
+ BackgroundColor #d3deff
+ BorderColor #0042b3
+ FontColor #00134a
+}
+
+skinparam sequence {
+ LifeLineBorderColor #586a88
+ GroupBackgroundColor #d9e3f9
+ GroupBorderColor #586a88
+ GroupFontColor #00134a
+ GroupHeaderFontColor #00134a
+ DividerBackgroundColor #d9e3f9
+ DividerBorderColor #586a88
+ DividerFontColor #00134a
+}
+
+skinparam note {
+ BackgroundColor #f1f1f4
+ BorderColor #586a88
+ FontColor #00134a
+}
+
+skinparam rectangle {
+ RoundCorner 8
+ BackgroundColor #ffffff
+ BorderColor #586a88
+ FontColor #00134a
+}
+
+skinparam package {
+ BackgroundColor #ffffff
+ BorderColor #586a88
+ FontColor #00134a
+}
+
+skinparam class {
+ HeaderBackgroundColor #d3deff
+ BackgroundColor #ffffff
+ BorderColor #0042b3
+ FontColor #00134a
+ AttributeFontColor #00134a
+}
+
+skinparam activity {
+ BackgroundColor #d3deff
+ BorderColor #0042b3
+ FontColor #00134a
+ StartColor #0042b3
+ EndColor #0042b3
+ BarColor #586a88
+ DiamondBackgroundColor #d9e3f9
+ DiamondBorderColor #586a88
+ DiamondFontColor #00134a
+}
