Skip to content

Commit 5f183a6

Browse files
authored
Merge pull request italia#704 from fmarino-ipzs/plantuml
Figures/Diagrams conversion into plantuml
2 parents af62e4a + 93c08d1 commit 5f183a6

File tree

127 files changed

+2174
-1763
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

127 files changed

+2174
-1763
lines changed

.github/workflows/gh-pages.yml

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,19 @@ jobs:
5050
- name: Install deps
5151
run: |-
5252
python -m pip install -r requirements-dev.txt
53+
54+
# Required by plantuml
55+
- name: Setup Java
56+
uses: actions/setup-java@v3
57+
with:
58+
distribution: 'temurin'
59+
java-version: '17'
60+
61+
# Required by plantuml
62+
- name: Install Graphviz
63+
run: |
64+
sudo apt-get update
65+
sudo apt-get install -y graphviz
5366
5467
- name: Build branch
5568
run: |-

.gitignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,13 @@ Thumbs.db
1313
*.swp
1414
html
1515
env
16+
venv
1617
build
1718
latex
1819
env-preview
1920
.venv
2021
.vscode
21-
*.py
22+
#*.py
2223
*.cfg
2324
*.tmpl
2425
*.exe

CONTRIBUTING-RULES.md

Lines changed: 72 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,12 @@ This guide provides guidelines for contributing to IT-Wallet Technical Documenta
1515
- [Referencing RFC Documents](#referencing-rfc-documents)
1616
- [Important Syntax Notes](#important-syntax-notes)
1717
- [Figures and Images](#figures-and-images)
18-
- [Image Requirements](#image-requirements)
18+
- [Image Formats and Requirements](#image-formats-and-requirements)
19+
- [File Organization for Images](#file-organization-for-images)
20+
- [Adding Images to Documentation](#adding-images-to-documentation)
21+
- [SVG and PDF Images](#svg-and-pdf-images)
22+
- [PlantUML Diagrams](#plantuml-diagrams)
23+
- [Image Attributes](#image-attributes)
1924
- [Cross-Referencing Figures](#cross-referencing-figures)
2025
- [Tables](#tables)
2126
- [Table Requirements](#table-requirements)
@@ -131,51 +136,91 @@ These references will automatically link to the appropriate RFC document without
131136

132137
## Figures and Images
133138

134-
Use the `figure` directive for images, preferably in SVG format for diagrams:
139+
This section describes how to include figures and images in the documentation, supporting both HTML and PDF output formats.
140+
141+
### Image Formats and Requirements
142+
143+
The documentation supports two main approaches for figures:
144+
145+
1. **Static Images** (SVG and PDF)
146+
- SVG format is required for HTML output
147+
- PDF format is required for LaTeX/PDF output
148+
- Both formats must be provided for each image
149+
- A tool is available in `./docs/utils/svg2pdf.py` to automatically convert SVG to PDF
150+
151+
2. **PlantUML Diagrams**
152+
- All architecture, component, or sequence diagrams must be created using PlantUML
153+
- PlantUML's official Standard Library (stdlib) may be used if required
154+
- For technical details about available libraries, refer to [PlantUML's official Standard Library Documentation](https://plantuml.com/stdlib)
155+
156+
The approaches are mutually exclusive - use either static images OR PlantUML diagrams for a given figure.
157+
158+
### File Organization for Images
159+
160+
Images must be organized in specific directories based on their format:
161+
162+
- **SVG images**: Store in `./docs/en/images/svg/`
163+
- **PDF images**: Store in `./docs/en/images/pdf/`
164+
- **PlantUML diagrams**: Store source files in `./docs/en/plantuml/` with `.puml` extension
165+
166+
### Adding Images to Documentation
167+
168+
#### SVG and PDF Images
169+
170+
For static images, use conditional directives to include the appropriate format based on the output target:
135171

136172
```rst
137173
.. _fig_reference_name:
138-
.. figure:: ../../images/diagram-name.svg
139-
:figwidth: 90%
174+
175+
.. only:: format_html
176+
177+
.. figure:: ./images/svg/diagram-name.svg
178+
:alt: Description of the diagram
179+
:width: 100%
140180
:align: center
141-
:target: https://www.plantuml.com/plantuml/svg/ENCODED-URL
142181
143182
Caption text describing the figure.
144-
```
145183
146-
### Image Requirements
184+
.. only:: format_latex
147185
148-
- **Format**: All images must be in SVG format for optimal rendering and scalability
149-
- **Diagrams**: All architecture, component or sequence diagrams must be created using PlantUML with C4 Component modeling
150-
- **Attributes**:
151-
- `:figwidth:` - REQUIRED (usually specified as percentage, e.g., `90%`)
152-
- `:align:` - REQUIRED (typically `center`)
153-
- Caption text - REQUIRED (appears below the figure)
154-
- `:target:` - REQUIRED for PlantUML diagrams (must link to the PlantUML source)
155-
- Label (e.g., `.. _fig_reference_name:`) - Recommended for cross-referencing but optional. Use the prefix `_fig_` followed by the reference name
186+
.. figure:: ./images/pdf/diagram-name.pdf
187+
:alt: Description of the diagram
188+
:width: 100%
189+
:align: center
156190
157-
When working with figures, understand the difference between these key attributes:
191+
Caption text describing the figure.
192+
```
158193

159-
- **:figwidth:** Controls the width of the entire figure block, including the caption and any padding. It defines how much horizontal space the figure occupies in the document layout.
194+
#### PlantUML Diagrams
160195

161-
- **:width:** Controls only the width of the image itself, not the entire figure block. Use this when you need to resize just the image while allowing the caption to potentially be wider.
196+
For PlantUML diagrams, use the `plantuml` directive:
162197

163-
Example with both attributes:
164198
```rst
165-
.. figure:: ../../images/diagram-name.svg
166-
:figwidth: 90% # The entire figure block is 90% of the available width
167-
:width: 80% # The image itself is 80% of the figure block width
199+
.. _fig_reference_name:
200+
.. plantuml:: plantuml/diagram-name.puml
201+
:width: 99%
168202
:align: center
169-
:target: https://www.plantuml.com/plantuml/svg/ENCODED-URL
170-
171-
This is the caption that appears below the image.
203+
:alt: Description of the diagram
204+
:caption: `Caption text describing the figure. <https://www.plantuml.com/plantuml/svg/ENCODED-URL>`_
172205
```
173206

207+
Note that for PlantUML diagrams:
208+
- The `:caption:` attribute must include a link to the preview SVG on the PlantUML website
209+
- You do not need to use the `only::` directives as Sphinx will handle the output format automatically
210+
211+
### Image Attributes
212+
213+
When working with figures, understand the difference between these key attributes:
214+
215+
- **:figwidth:** Controls the width of the entire figure block, including the caption and any padding. It defines how much horizontal space the figure occupies in the document layout.
216+
217+
- **:width:** Controls only the width of the image itself, not the entire figure block. Use this when you need to resize just the image while allowing the caption to potentially be wider.
218+
174219
Other useful figure attributes:
175220
- **:height:** Controls the height of the image
176221
- **:scale:** Scales the image (e.g., `:scale: 50%`)
177-
- **:alt:** Provides alternative text for accessibility
178-
- **:name:** Used for internal references (can also use the separate label format shown above)
222+
- **:alt:** Provides alternative text for accessibility (REQUIRED)
223+
- **:align:** Specifies the alignment of the figure (typically `center`)
179224

180225
### Cross-Referencing Figures
181226

docs/common/symbols.rst

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,8 @@
1-
.. |check-icon| image:: ../../images/Eo_circle_green_checkmark.svg
2-
:width: 25
1+
.. |check-icon| image:: ../common/symbols/Eo_circle_green_checkmark.png
2+
:width: 25
33

4-
.. |partially-check-icon| image:: ../../images/Eo_circle_orange_checkmark.svg
5-
:width: 25
4+
.. |partially-check-icon| image:: ../common/symbols/Eo_circle_orange_checkmark.png
5+
:width: 25
66

7-
.. |uncheck-icon| image:: ../../images/Eo_circle_red_letter-x.svg
8-
:width: 25
9-
10-
.. |warning-message-it| replace:: Tutti gli esempi contenuti in questa documentazione sono da intendersi come non normativi
11-
.. |warning-message-en| replace:: All the examples contained in this documentation are meant to be non-normative
7+
.. |uncheck-icon| image:: ../common/symbols/Eo_circle_red_letter-x.png
8+
:width: 25
Loading
Loading
1.43 KB
Loading

docs/en/backup-restore.rst

Lines changed: 24 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,18 @@ Backup Flow
1919
-----------
2020

2121
.. _fig_Backup_flow:
22-
.. figure:: ../../images/Backup_flow.svg
23-
:name: Sequence Diagram for Wallet Instance Backup
24-
:figwidth: 90%
25-
:alt: The figure illustrates the sequence diagram for backup flow, with the steps explained below.
26-
:target: https://www.plantuml.com/plantuml/png/VP5HRzGm3CVVyodClMn8j1KmU9YcqxPZe8bDEkaqyG1eIbFlQaYJAd4uAhJlJj96WuvZUMhj_y_-spxrB1s7JejdP9GE3KBBtFlZgd9oLsw9sr07ZqvPmsYuLBQhUYrDOWhFZQQwMXqLwnIwkRwgEkaPNGpThY8XoQ0h-rHVICNMmKsi1TB38dqiXDWCKT_TdjjW6kc6mvtK6dbZTM2oviMaE_3m3d-GmiLp-2KWlltOfV4iZSA8VHe3a2CPpE_1sM6Wt24A6TsTJCezkbggxw4_wsc3Blc8rFaOWhFr9UHW9k_5dEriJHetR9tS9l1w_Cy3mPLLKaFE9fUvnhqG1t3nizUaY47BmGO6sNmBdZiq37VMGMyzfIsHsOfP5oW-jzGqQBuMIvYlHeXnt28c0i4nB4xgvSiIyZGhXv5YajgVLFLo8QBc96aVBs02NvNm0GqwoGWVSO1rwwJ7FsWYKxj9_ReSvzmZVLmT_j_og4mcKyCBezpGCpQGpRydZK_K2pHLU5F-Y-vp_8GKlXY8QTWHjx1sjkkdW_oL6-zQhRGDJRvkzlQm_ld5fePlInZ1ENAAfWcT_Wq0
22+
.. plantuml:: plantuml/backup-flow.puml
23+
:width: 90%
24+
:alt: The figure illustrates the sequence diagram for backup flow, with the steps explained below.
25+
:caption: `Backup flow <https://www.plantuml.com/plantuml/png/VP5HRzGm3CVVyodClMn8j1KmU9YcqxPZe8bDEkaqyG1eIbFlQaYJAd4uAhJlJj96WuvZUMhj_y_-spxrB1s7JejdP9GE3KBBtFlZgd9oLsw9sr07ZqvPmsYuLBQhUYrDOWhFZQQwMXqLwnIwkRwgEkaPNGpThY8XoQ0h-rHVICNMmKsi1TB38dqiXDWCKT_TdjjW6kc6mvtK6dbZTM2oviMaE_3m3d-GmiLp-2KWlltOfV4iZSA8VHe3a2CPpE_1sM6Wt24A6TsTJCezkbggxw4_wsc3Blc8rFaOWhFr9UHW9k_5dEriJHetR9tS9l1w_Cy3mPLLKaFE9fUvnhqG1t3nizUaY47BmGO6sNmBdZiq37VMGMyzfIsHsOfP5oW-jzGqQBuMIvYlHeXnt28c0i4nB4xgvSiIyZGhXv5YajgVLFLo8QBc96aVBs02NvNm0GqwoGWVSO1rwwJ7FsWYKxj9_ReSvzmZVLmT_j_og4mcKyCBezpGCpQGpRydZK_K2pHLU5F-Y-vp_8GKlXY8QTWHjx1sjkkdW_oL6-zQhRGDJRvkzlQm_ld5fePlInZ1ENAAfWcT_Wq0>`_
2726

28-
Backup flow.
27+
.. .. figure:: ../../images/Backup_flow.svg
28+
.. :name: Sequence Diagram for Wallet Instance Backup
29+
.. :figwidth: 90%
30+
.. :alt: The figure illustrates the sequence diagram for backup flow, with the steps explained below.
31+
.. :target: https://www.plantuml.com/plantuml/png/VP5HRzGm3CVVyodClMn8j1KmU9YcqxPZe8bDEkaqyG1eIbFlQaYJAd4uAhJlJj96WuvZUMhj_y_-spxrB1s7JejdP9GE3KBBtFlZgd9oLsw9sr07ZqvPmsYuLBQhUYrDOWhFZQQwMXqLwnIwkRwgEkaPNGpThY8XoQ0h-rHVICNMmKsi1TB38dqiXDWCKT_TdjjW6kc6mvtK6dbZTM2oviMaE_3m3d-GmiLp-2KWlltOfV4iZSA8VHe3a2CPpE_1sM6Wt24A6TsTJCezkbggxw4_wsc3Blc8rFaOWhFr9UHW9k_5dEriJHetR9tS9l1w_Cy3mPLLKaFE9fUvnhqG1t3nizUaY47BmGO6sNmBdZiq37VMGMyzfIsHsOfP5oW-jzGqQBuMIvYlHeXnt28c0i4nB4xgvSiIyZGhXv5YajgVLFLo8QBc96aVBs02NvNm0GqwoGWVSO1rwwJ7FsWYKxj9_ReSvzmZVLmT_j_og4mcKyCBezpGCpQGpRydZK_K2pHLU5F-Y-vp_8GKlXY8QTWHjx1sjkkdW_oL6-zQhRGDJRvkzlQm_ld5fePlInZ1ENAAfWcT_Wq0
32+
33+
.. Backup flow.
2934
3035
Below, the description of the steps of :numref:`fig_Backup_flow`:
3136

@@ -121,13 +126,20 @@ Restore flow for Hardware Binding Credential
121126
--------------------------------------------
122127

123128
.. _fig_Restore_flow:
124-
.. figure:: ../../images/Restore_Flow.svg
125-
:name: Sequence Diagram for Wallet Instance Restore
126-
:figwidth: 90%
127-
:alt: The figure illustrates the sequence diagram for restore flow, with the steps explained below.
128-
:target: https://www.plantuml.com/plantuml/png/TP5DRnCn48Rl-ok6N9fAP5T0-L0LHVrea2fQ4OWg3e2gsVKqCNZjbJrk6w7-T-or5TYssPCpVfzd9kCZnsZPjwfu8NMZl21OCtVkiAeitfKhoMjVUqUsCPf9SzcOjkeKwiXC70ibw-hqOBA8fQlBYwf5nsH3wVeq42WrsRAB_W8RDXQkWWlGmIWUHaMnt8HyUtrYl1PeD-CxL8fuQPHdQVJBbDjpS4Qtig7HFlmf87pFO-VQCUg60lQjBq2kP31_syd6NkOE8SXaRp0cdydLsFpstN4dbsJZ784wwKjml3Y7NCpaGr4CuTRKKj6IZSLL92_xt_aVmOLfK46wJMCcoSDsD_Dx7fyxvya6E1r2gs8FvlUTaeraKBWndW75B--u9SrmOonqnicuHAbNnM06c7nVIo58_vpCOBYvgFrA2YFdrh9pHR-TaFCI3c4qhMUlof1mmKIGbZojwjaevQQJVxdN9IoiQJi6Dd3LAOC2yj8-IaK3QWR30PFXJGbBKjJm_npS12dau5QIHqpSGT_vLWg2kMxifcCI0mLg4MuuK9ze0ukrHKSkkRoCfiVldRnlozs-fwR7ZjtUToMSKVP65dxeKCqDaYmzEpnvhoHuNyBdcb5gk2H6WOn3RBg3-r12du3nb_tv_BXde3WYBNoh_W80
129129

130-
Restore flow.
130+
.. plantuml:: plantuml/restore-flow.puml
131+
:width: 90%
132+
:alt: The figure illustrates the sequence diagram for restore flow, with the steps explained below.
133+
:caption: `Restore Flow <https://www.plantuml.com/plantuml/png/TP5DRnCn48Rl-ok6N9fAP5T0-L0LHVrea2fQ4OWg3e2gsVKqCNZjbJrk6w7-T-or5TYssPCpVfzd9kCZnsZPjwfu8NMZl21OCtVkiAeitfKhoMjVUqUsCPf9SzcOjkeKwiXC70ibw-hqOBA8fQlBYwf5nsH3wVeq42WrsRAB_W8RDXQkWWlGmIWUHaMnt8HyUtrYl1PeD-CxL8fuQPHdQVJBbDjpS4Qtig7HFlmf87pFO-VQCUg60lQjBq2kP31_syd6NkOE8SXaRp0cdydLsFpstN4dbsJZ784wwKjml3Y7NCpaGr4CuTRKKj6IZSLL92_xt_aVmOLfK46wJMCcoSDsD_Dx7fyxvya6E1r2gs8FvlUTaeraKBWndW75B--u9SrmOonqnicuHAbNnM06c7nVIo58_vpCOBYvgFrA2YFdrh9pHR-TaFCI3c4qhMUlof1mmKIGbZojwjaevQQJVxdN9IoiQJi6Dd3LAOC2yj8-IaK3QWR30PFXJGbBKjJm_npS12dau5QIHqpSGT_vLWg2kMxifcCI0mLg4MuuK9ze0ukrHKSkkRoCfiVldRnlozs-fwR7ZjtUToMSKVP65dxeKCqDaYmzEpnvhoHuNyBdcb5gk2H6WOn3RBg3-r12du3nb_tv_BXde3WYBNoh_W80>`_
134+
135+
136+
.. .. figure:: ../../images/Restore_Flow.svg
137+
.. :name: Sequence Diagram for Wallet Instance Restore
138+
.. :figwidth: 90%
139+
.. :alt: The figure illustrates the sequence diagram for restore flow, with the steps explained below.
140+
.. :target: https://www.plantuml.com/plantuml/png/TP5DRnCn48Rl-ok6N9fAP5T0-L0LHVrea2fQ4OWg3e2gsVKqCNZjbJrk6w7-T-or5TYssPCpVfzd9kCZnsZPjwfu8NMZl21OCtVkiAeitfKhoMjVUqUsCPf9SzcOjkeKwiXC70ibw-hqOBA8fQlBYwf5nsH3wVeq42WrsRAB_W8RDXQkWWlGmIWUHaMnt8HyUtrYl1PeD-CxL8fuQPHdQVJBbDjpS4Qtig7HFlmf87pFO-VQCUg60lQjBq2kP31_syd6NkOE8SXaRp0cdydLsFpstN4dbsJZ784wwKjml3Y7NCpaGr4CuTRKKj6IZSLL92_xt_aVmOLfK46wJMCcoSDsD_Dx7fyxvya6E1r2gs8FvlUTaeraKBWndW75B--u9SrmOonqnicuHAbNnM06c7nVIo58_vpCOBYvgFrA2YFdrh9pHR-TaFCI3c4qhMUlof1mmKIGbZojwjaevQQJVxdN9IoiQJi6Dd3LAOC2yj8-IaK3QWR30PFXJGbBKjJm_npS12dau5QIHqpSGT_vLWg2kMxifcCI0mLg4MuuK9ze0ukrHKSkkRoCfiVldRnlozs-fwR7ZjtUToMSKVP65dxeKCqDaYmzEpnvhoHuNyBdcb5gk2H6WOn3RBg3-r12du3nb_tv_BXde3WYBNoh_W80
141+
142+
.. Restore flow.
131143
132144
Considering that the User has initialized the new Wallet Instance and it is in active state by obtaining a new PID, this specification relaxes the requirement of the ARF concerning the addition of the PID in the backup file.
133145
Below, the description of the steps of :numref:`fig_Restore_flow`:

docs/en/brand-identity.rst

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -102,10 +102,17 @@ Verifiers MUST make the Authentication Button available within the Discovery Pag
102102

103103
The integration of the Authentication Button within the Discovery Page may vary depending on the page layout. Below are illustrative, non-exhaustive examples of Discovery Pages using grid, tab, and list layouts, respectively.
104104

105-
.. figure:: ../../images/discovery-page-layouts.svg
106-
:name: Examples of Discovery Page layouts: grid, tab, and list
107-
:alt: examples of Discovery Page layouts: grid, tab, and list
108-
:width: 100%
105+
.. only:: format_html
106+
107+
.. figure:: ./images/svg/discovery-page-layouts.svg
108+
:alt: examples of Discovery Page layouts: grid, tab, and list
109+
:width: 100%
110+
111+
.. only:: format_latex
112+
113+
.. figure:: ./images/pdf/discovery-page-layouts.pdf
114+
:alt: examples of Discovery Page layouts: grid, tab, and list
115+
:width: 100%
109116

110117
For further details on the use of the Authentication Button, please refer to the :ref:`functionalities:Authentication` section.
111118

docs/en/conf.py

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@
1313
version = settings_doc_version
1414

1515
import sys, os
16+
from pathlib import Path
17+
confdir = Path(__file__).resolve().parent
1618

1719
# -- RTD configuration -------------------------------------------------
1820

@@ -48,6 +50,7 @@
4850
'sphinx.ext.autosectionlabel',
4951
'sphinxcontrib.redoc',
5052
'myst_parser',
53+
'sphinxcontrib.plantuml'
5154
]
5255

5356
redoc = [
@@ -77,6 +80,13 @@
7780
.. _blank: target="_blank"
7881
"""
7982

83+
plantuml_jar = confdir.parent.parent / "utils/plantuml/plantuml-1.2025.2.jar"
84+
plantuml = f'java -jar {str(plantuml_jar)}'
85+
plantuml_output_format = 'svg'
86+
plantuml_latex_output_format = 'pdf'
87+
plantuml_server = ''
88+
#plantuml_cache_path = './cache'
89+
8090
images_config = {
8191
"default_image_width": "99%",
8292
"align": "center"
@@ -273,7 +283,7 @@
273283
# (source start file, target name, title,
274284
# author, documentclass [howto, manual, or own class]).
275285
latex_documents = [
276-
('index', settings_file_name + '.tex', settings_project_name, "This document was prepared by a team of contributors", 'manual'),
286+
('index', settings_file_name + '.tex', f"{settings_project_name} - {version}", settings_editor_name, 'manual'),
277287
]
278288

279289
# The name of an image file (relative to this directory) to place at the top of

0 commit comments

Comments
 (0)