Merge pull request italia#704 from fmarino-ipzs/plantuml

Figures/Diagrams conversion into plantuml

Author: peppelinux

.github/workflows/gh-pages.yml

@@ -50,6 +50,19 @@ jobs:
       - name: Install deps
         run: |-
           python -m pip install -r requirements-dev.txt
+      
+      # Required by plantuml
+      - name: Setup Java
+        uses: actions/setup-java@v3
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+
+      # Required by plantuml
+      - name: Install Graphviz
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y graphviz
 
       - name: Build branch
         run: |-

.gitignore

@@ -13,12 +13,13 @@ Thumbs.db
 *.swp
 html
 env
+venv
 build
 latex
 env-preview
 .venv
 .vscode
-*.py
+#*.py
 *.cfg
 *.tmpl
 *.exe

CONTRIBUTING-RULES.md

@@ -15,7 +15,12 @@ This guide provides guidelines for contributing to IT-Wallet Technical Documenta
       - [Referencing RFC Documents](#referencing-rfc-documents)
       - [Important Syntax Notes](#important-syntax-notes)
   - [Figures and Images](#figures-and-images)
-    - [Image Requirements](#image-requirements)
+    - [Image Formats and Requirements](#image-formats-and-requirements)
+    - [File Organization for Images](#file-organization-for-images)
+    - [Adding Images to Documentation](#adding-images-to-documentation)
+      - [SVG and PDF Images](#svg-and-pdf-images)
+      - [PlantUML Diagrams](#plantuml-diagrams)
+    - [Image Attributes](#image-attributes)
     - [Cross-Referencing Figures](#cross-referencing-figures)
   - [Tables](#tables)
     - [Table Requirements](#table-requirements)
@@ -131,51 +136,91 @@ These references will automatically link to the appropriate RFC document without
 
 ## Figures and Images
 
-Use the `figure` directive for images, preferably in SVG format for diagrams:
+This section describes how to include figures and images in the documentation, supporting both HTML and PDF output formats.
+
+### Image Formats and Requirements
+
+The documentation supports two main approaches for figures:
+
+1. **Static Images** (SVG and PDF)
+   - SVG format is required for HTML output
+   - PDF format is required for LaTeX/PDF output
+   - Both formats must be provided for each image
+   - A tool is available in `./docs/utils/svg2pdf.py` to automatically convert SVG to PDF
+
+2. **PlantUML Diagrams**
+   - All architecture, component, or sequence diagrams must be created using PlantUML
+   - PlantUML's official Standard Library (stdlib) may be used if required
+   - For technical details about available libraries, refer to [PlantUML's official Standard Library Documentation](https://plantuml.com/stdlib)
+
+The approaches are mutually exclusive - use either static images OR PlantUML diagrams for a given figure.
+
+### File Organization for Images
+
+Images must be organized in specific directories based on their format:
+
+- **SVG images**: Store in `./docs/en/images/svg/`
+- **PDF images**: Store in `./docs/en/images/pdf/`
+- **PlantUML diagrams**: Store source files in `./docs/en/plantuml/` with `.puml` extension
+
+### Adding Images to Documentation
+
+#### SVG and PDF Images
+
+For static images, use conditional directives to include the appropriate format based on the output target:
 
 ```rst
 .. _fig_reference_name:
-.. figure:: ../../images/diagram-name.svg
-    :figwidth: 90%
+
+.. only:: format_html
+
+  .. figure:: ./images/svg/diagram-name.svg
+    :alt: Description of the diagram
+    :width: 100%
     :align: center
-    :target: https://www.plantuml.com/plantuml/svg/ENCODED-URL
 
     Caption text describing the figure.
-```
 
-### Image Requirements
+.. only:: format_latex
 
-- **Format**: All images must be in SVG format for optimal rendering and scalability
-- **Diagrams**: All architecture, component or sequence diagrams must be created using PlantUML with C4 Component modeling
-- **Attributes**:
-  - `:figwidth:` - REQUIRED (usually specified as percentage, e.g., `90%`)
-  - `:align:` - REQUIRED (typically `center`)
-  - Caption text - REQUIRED (appears below the figure)
-  - `:target:` - REQUIRED for PlantUML diagrams (must link to the PlantUML source)
-  - Label (e.g., `.. _fig_reference_name:`) - Recommended for cross-referencing but optional. Use the prefix `_fig_` followed by the reference name
+  .. figure:: ./images/pdf/diagram-name.pdf
+    :alt: Description of the diagram
+    :width: 100%
+    :align: center
 
-When working with figures, understand the difference between these key attributes:
+    Caption text describing the figure.
+```
 
-- **: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.
+#### PlantUML Diagrams
 
-- **: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.
+For PlantUML diagrams, use the `plantuml` directive:
 
-Example with both attributes:
 ```rst
-.. figure:: ../../images/diagram-name.svg
-    :figwidth: 90%  # The entire figure block is 90% of the available width
-    :width: 80%     # The image itself is 80% of the figure block width
+.. _fig_reference_name:
+.. plantuml:: plantuml/diagram-name.puml
+    :width: 99%
     :align: center
-    :target: https://www.plantuml.com/plantuml/svg/ENCODED-URL
-
-    This is the caption that appears below the image.
+    :alt: Description of the diagram
+    :caption: `Caption text describing the figure. <https://www.plantuml.com/plantuml/svg/ENCODED-URL>`_
 ```
 
+Note that for PlantUML diagrams:
+- The `:caption:` attribute must include a link to the preview SVG on the PlantUML website
+- You do not need to use the `only::` directives as Sphinx will handle the output format automatically
+
+### Image Attributes
+
+When working with figures, understand the difference between these key attributes:
+
+- **: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.
+
+- **: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.
+
 Other useful figure attributes:
 - **:height:** Controls the height of the image
 - **:scale:** Scales the image (e.g., `:scale: 50%`)
-- **:alt:** Provides alternative text for accessibility
-- **:name:** Used for internal references (can also use the separate label format shown above)
+- **:alt:** Provides alternative text for accessibility (REQUIRED)
+- **:align:** Specifies the alignment of the figure (typically `center`)
 
 ### Cross-Referencing Figures
 

docs/common/symbols.rst

@@ -1,11 +1,8 @@
-.. |check-icon| image:: ../../images/Eo_circle_green_checkmark.svg
-   :width: 25
+.. |check-icon| image:: ../common/symbols/Eo_circle_green_checkmark.png
+    :width: 25
 
-.. |partially-check-icon| image:: ../../images/Eo_circle_orange_checkmark.svg
-   :width: 25
+.. |partially-check-icon| image:: ../common/symbols/Eo_circle_orange_checkmark.png
+    :width: 25
 
-.. |uncheck-icon| image:: ../../images/Eo_circle_red_letter-x.svg
-   :width: 25
-
-.. |warning-message-it| replace:: Tutti gli esempi contenuti in questa documentazione sono da intendersi come non normativi
-.. |warning-message-en| replace:: All the examples contained in this documentation are meant to be non-normative
+.. |uncheck-icon| image:: ../common/symbols/Eo_circle_red_letter-x.png
+    :width: 25

docs/common/symbols/Eo_circle_green_checkmark.png

@@ -19,13 +19,18 @@ Backup Flow
 -----------
 
 .. _fig_Backup_flow:
-.. figure:: ../../images/Backup_flow.svg
-  :name: Sequence Diagram for Wallet Instance Backup
-  :figwidth: 90%
-  :alt: The figure illustrates the sequence diagram for backup flow, with the steps explained below.
-  :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
+.. plantuml:: plantuml/backup-flow.puml
+   :width: 90%
+   :alt: The figure illustrates the sequence diagram for backup flow, with the steps explained below.
+   :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>`_
 
-  Backup flow.
+.. .. figure:: ../../images/Backup_flow.svg
+..   :name: Sequence Diagram for Wallet Instance Backup
+..   :figwidth: 90%
+..   :alt: The figure illustrates the sequence diagram for backup flow, with the steps explained below.
+..   :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
+
+  .. Backup flow.
 
 Below, the description of the steps of :numref:`fig_Backup_flow`:
 
@@ -121,13 +126,20 @@ Restore flow for Hardware Binding Credential
 --------------------------------------------
 
 .. _fig_Restore_flow:
-.. figure:: ../../images/Restore_Flow.svg
-  :name: Sequence Diagram for Wallet Instance Restore
-  :figwidth: 90%
-  :alt: The figure illustrates the sequence diagram for restore flow, with the steps explained below.
-  :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
 
-  Restore flow.
+.. plantuml:: plantuml/restore-flow.puml
+   :width: 90%
+   :alt: The figure illustrates the sequence diagram for restore flow, with the steps explained below.
+   :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>`_
+    
+
+.. .. figure:: ../../images/Restore_Flow.svg
+..   :name: Sequence Diagram for Wallet Instance Restore
+..   :figwidth: 90%
+..   :alt: The figure illustrates the sequence diagram for restore flow, with the steps explained below.
+..   :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
+
+..   Restore flow.
 
 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.
 Below, the description of the steps of :numref:`fig_Restore_flow`:

docs/common/symbols/Eo_circle_orange_checkmark.png

@@ -102,10 +102,17 @@ Verifiers MUST make the Authentication Button available within the Discovery Pag
 
 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.
 
-.. figure:: ../../images/discovery-page-layouts.svg
-  :name: Examples of Discovery Page layouts: grid, tab, and list
-  :alt: examples of Discovery Page layouts: grid, tab, and list
-  :width: 100%
+.. only:: format_html
+
+  .. figure:: ./images/svg/discovery-page-layouts.svg
+    :alt: examples of Discovery Page layouts: grid, tab, and list
+    :width: 100%
+
+.. only:: format_latex 
+  
+  .. figure:: ./images/pdf/discovery-page-layouts.pdf
+    :alt: examples of Discovery Page layouts: grid, tab, and list
+    :width: 100%
 
 For further details on the use of the Authentication Button, please refer to the :ref:`functionalities:Authentication` section.
 

docs/common/symbols/Eo_circle_red_letter-x.png

@@ -13,6 +13,8 @@
 version = settings_doc_version
 
 import sys, os
+from pathlib import Path
+confdir = Path(__file__).resolve().parent
 
 # -- RTD configuration -------------------------------------------------
 
@@ -48,6 +50,7 @@
     'sphinx.ext.autosectionlabel',
     'sphinxcontrib.redoc',
     'myst_parser',  
+    'sphinxcontrib.plantuml'
 ]
 
 redoc = [
@@ -77,6 +80,13 @@
 .. _blank: target="_blank"
 """
 
+plantuml_jar = confdir.parent.parent / "utils/plantuml/plantuml-1.2025.2.jar"
+plantuml = f'java -jar {str(plantuml_jar)}'
+plantuml_output_format = 'svg'
+plantuml_latex_output_format = 'pdf'
+plantuml_server = ''
+#plantuml_cache_path = './cache'
+
 images_config = {
     "default_image_width": "99%",
     "align": "center"
@@ -273,7 +283,7 @@
 # (source start file, target name, title,
 # author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  ('index', settings_file_name + '.tex', settings_project_name, "This document was prepared by a team of contributors", 'manual'),
+  ('index', settings_file_name + '.tex', f"{settings_project_name} - {version}", settings_editor_name, 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of