Terminology and sphinx template (#368)

* fix!: alignments according to breaking changes introduced by openid4vci I-D * editorials about IT-Wallet and introductions * sphix update and piccolo theme, docs italia removed * terminology and sphinx template * fix: CI with py38 * fix: it sphinx conf
italia · Jul 30, 2024 · e58ad09 · e58ad09
1 parent 82c2836
commit e58ad09
Show file tree

Hide file tree

Showing 13 changed files with 163 additions and 69 deletions.
diff --git a/.github/workflows/ci-html.yml b/.github/workflows/ci-html.yml
@@ -43,7 +43,7 @@ jobs:
 
       - uses: actions/setup-python@v2
         with:
-          python-version: '3.8' # Version range or exact version of a Python version to use, using SemVer's version range syntax
+          python-version: '3.10' # Version range or exact version of a Python version to use, using SemVer's version range syntax
           architecture: 'x64' # optional x64 or x86. Defaults to x64 if not specified
 
       # Runs a single command using the runners shell

diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
@@ -44,7 +44,7 @@ jobs:
 
       - uses: actions/setup-python@v2
         with:
-          python-version: "3.8" # Version range or exact version of a Python version to use, using SemVer's version range syntax
+          python-version: "3.10" # Version range or exact version of a Python version to use, using SemVer's version range syntax
           architecture: "x64" # optional x64 or x86. Defaults to x64 if not specified
 
       - name: Install deps

diff --git a/.github/workflows/latex.yml b/.github/workflows/latex.yml
@@ -27,7 +27,7 @@ jobs:
 
       - uses: actions/setup-python@v2
         with:
-          python-version: '3.8' # Version range or exact version of a Python version to use, using SemVer's version range syntax
+          python-version: '3.10' # Version range or exact version of a Python version to use, using SemVer's version range syntax
           architecture: 'x64' # optional x64 or x86. Defaults to x64 if not specified
 
       # TODO: temporary disabled

diff --git a/README.md b/README.md
@@ -62,10 +62,6 @@ HTML
 ````
 pip install -r requirements.txt
 
-# italian version
-sphinx-build -b html -d html/it/doctrees docs/it/  html/it
-
-# english version
 sphinx-build -b html -d html/en/doctrees docs/en/  html/en
 ````
 

diff --git a/docs/en/conf.py b/docs/en/conf.py
@@ -13,7 +13,6 @@
 # -- No need to change below here
 
 import sys, os
-docs_italia_theme = __import__("docs_italia_theme")
 from recommonmark.transform import AutoStructify
 from recommonmark.parser import CommonMarkParser
 
@@ -48,7 +47,6 @@
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.ifconfig',
-    'docs_italia_theme',
     'sphinx.ext.autosectionlabel',
 ]
 
@@ -112,9 +110,9 @@ def setup(app):
 
 
 # -- Options for HTML output ----------------------------------------------
-html_theme = 'docs-italia-theme'
+html_theme = 'piccolo_theme'
 
-html_theme_path = [docs_italia_theme.get_html_theme_path()]
+# html_theme_path = [docs_italia_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -131,8 +129,9 @@ def setup(app):
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
 if not on_rtd:  # only import and set the theme if we're building docs locally
-    html_theme_path = [docs_italia_theme.get_html_theme_path()]
-    html_theme = 'docs_italia_theme'
+    #  html_theme_path = [docs_italia_theme.get_html_theme_path()]
+    #  html_theme = 'docs_italia_theme'
+    pass
 else:
     # Override default css to get a larger width for ReadTheDoc build
     html_context = {

diff --git a/docs/en/contribute.rst b/docs/en/contribute.rst
@@ -5,7 +5,7 @@
 How to contribute
 +++++++++++++++++++++++++++
 
-The IT Wallet project, including this document, follows an **open development process**. This approach ensures the development process is accessible to all, inviting all interested parties to participate.
+The IT-Wallet project, including this document, follows an **open development process**. This approach ensures the development process is accessible to all, inviting all interested parties to participate.
 
 Consequently, stakeholders, national and international community members are not only encouraged but also heartily welcomed to contribute to the refinement of these technical rules.
 

diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst
diff --git a/docs/en/index.rst b/docs/en/index.rst
@@ -9,11 +9,11 @@ Introduction
 
 The European Parliament `has adopted <https://www.europarl.europa.eu/doceo/document/A-9-2023-0038_EN.html#_section1>`_ the revision of the eIDAS Regulation concerning electronic identification and trust services, introducing a significant innovation: the `European Digital Identity Wallet <https://commission.europa.eu/strategy-and-policy/priorities-2019-2024/europe-fit-digital-age/european-digital-identity_en>`_. This update marks a pivotal advancement in the EU's digital strategy, aiming to enhance the security, interoperability, and usability of digital identities across Member States. For further details, resources, and notes on this legislative development, please refer to the official EU Commission and Parliament websites.
 
-Italy has launched the National digital identity Wallet solution, known as IT Wallet, in direct response to the European community's directives. This initiative ensures full interoperability with the digital identity solutions provided by other European Member States, aligning completely with European regulations.
+Italy has launched the National digital identity Wallet solution, known as IT-Wallet, established by the Legislative Decree of March 2, 2024, No. 19 (commonly referred to as the PNRR Decree)., in direct response to the European community's directives. This initiative ensures full interoperability with the digital identity solutions provided by other European Member States, aligning with European regulations.
 
-The purpose of the following technical rules is to define the technical architecture and reference framework to be used as a guideline by all the parties involved in the development of the IT Wallet project.
+The purpose of the following technical rules is to define the technical architecture and reference framework to be used as a guideline by all the parties involved in the development of the IT-Wallet project.
 
-This documentation defines the national implementation profile of EUDI Wallet, containing the technical details about components of the Wallet ecosystem, as listed below:
+This documentation defines the national implementation profile of IT-Wallet, containing the technical details about components of the Wallet ecosystem, as listed below:
 
  - Entities of the ecosystem according to `EIDAS-ARF`_.
  - Infrastructure of trust attesting realiability and eligibility of the participants.

diff --git a/docs/en/trust.rst b/docs/en/trust.rst
@@ -17,12 +17,12 @@ The Infrastructure of trust facilitates the application of a trust assessment me
 
     The roles within the Federation, where the Trust Anchor oversees its subordinates,
     which include one or more Intermediates and Leaves. In this
-    representation, both the Trust Anchor and the Intermediates MAY assume the role of Accreditation Body.
+    representation, both the Trust Anchor and the Intermediates assume the role of Registration Authority.
 
 Federation Roles
 ------------------
 
-All the participants are Federation Entities that MUST be accredited by an Accreditation Body,
+All the participants are Federation Entities that MUST be registered by an Registration Body,
 except for Wallet Instances which are End-User's personal devices certified by their Wallet Provider.
 
 .. note::
@@ -137,11 +137,11 @@ This section includes the requirements necessary for the successful implementati
    * - [FR #21]
      - **Future-Proof Cryptography**: the system should employ a flexible cryptographic framework that can be updated in response to new threats or advancements in cryptographic research, ensuring long-term security and integrity of federation operations.
    * - [FR #23]
-     - **Autonomous Accreditation Bodies**: the system must facilitate the integration of autonomous accreditation bodies that operate in compliance with federation rules. These bodies are tasked with evaluating and accrediting entities within the federation, according to the pre-established rules and their compliance that must be periodically asserted.
+     - **Autonomous Registration Bodies**: the system must facilitate the integration of autonomous registration bodies that operate in compliance with federation rules. These bodies are tasked with evaluating and accrediting entities within the federation, according to the pre-established rules and their compliance that must be periodically asserted.
    * - [FR #24]
-     - **Compliance Evaluation for Federation Entity Candidates**: accreditation bodies must evaluate the compliance of candidate entities against federation standards before their registration in the federation.
+     - **Compliance Evaluation for Federation Entity Candidates**: registration bodies must evaluate the compliance of candidate entities against federation standards before their registration in the federation.
    * - [FR #25]
-     - **Periodic Auditing of Accreditation Bodies and Entities**: implement mechanisms for the periodic auditing and monitoring of the compliance status of both accreditation bodies and their accredited entities. This ensures ongoing adherence to federation standards and policies.
+     - **Periodic Auditing of Registration Bodies and Entities**: implement mechanisms for the periodic auditing and monitoring of the compliance status of both registration bodies and their accredited entities. This ensures ongoing adherence to federation standards and policies.
    * - [FR #26]
      - **Certification of Compliance for Personal Devices**: trusted bodies, in the form of federation entities, should issue certifications of compliance and provide signed proof of such compliance for the hardware of personal devices used within the federation. These certifications should be attested and periodically renewed to ensure the devices meet current security standards.
    * - [FR #27]
@@ -454,7 +454,7 @@ Trust Anchors and Intermediates MUST expose the Federation Fetch endpoint, where
 .. note:: 
     The Federation Fetch endpoint MAY also publish X.509 certificates for each of the public keys of the Subordinate. Making the distribution of the issued X.509 certificates via a RESTful service.
 
-Below there is a non-normative example of an Entity Statement issued by an Accreditation Body (such as the Trust Anchor or its Intermediate) in relation to one of its Subordinates.
+Below there is a non-normative example of an Entity Statement issued by an Registration Body (such as the Trust Anchor or its Intermediate) in relation to one of its Subordinates.
 
 .. code-block:: text
 
@@ -639,7 +639,7 @@ Offline Trust Attestation Mechanisms
 The offline flows do not allow for real-time evaluation of an Entity's status, such as its revocation. At the same time, using short-lived Trust Chains enables the attainment of trust attestations compatible with the required revocation administrative protocols (e.g., a revocation must be propagated in less than 24 hours, thus the Trust Chain must not be valid for more than that period).
 
 
-Offline EUDI Wallet Trust Attestation
+Offline Wallet Trust Attestation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Given that the Wallet Instance cannot publish its metadata online at the *.well-known/openid-federation* endpoint, 

diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst
@@ -106,7 +106,7 @@ Wallet Instance Initialization and Registration
     **Device Integrity Service**: In this section the Device Integrity Service is considered as it is provided by device manufacturers. This service allows the verification of a key being securely stored within the device's hardware through a signed object. Additionally, it offers the verifiable proof that a specific Wallet Instance is authentic, unaltered, and in its original state using a specialized signed document made for this scope.
 
     The service also incorporates details in the signed object, such as the device type, model, app version, operating system version, bootloader status, and other relevant information to assess the device has not been compromised. For Android, the DIS is represented by *Key Attestation*, a feature supported by *StrongBox Keymaster*, which is a physical HSM installed directly on the motherboard, and the *TEE* (Trusted Execution Environment), a secure area of the main processor. *Key Attestation* aims to provide a way to strongly determine if a key pair is hardware-backed, what the properties of the key are, and what constraints are applied to its usage. Developers can leverage its functionality through the *Play Integrity API*.For Apple devices, the DIS is represented by *DeviceCheck*, which provides a framework and server interface to manage device-specific data securely. *DeviceCheck* is used in combination with the *Secure Enclave*, a dedicated HSM integrated into Apple's SoCs. *DeviceCheck* can be used to attest the integrity of the device, apps, and/or encryption keys generated on the device, ensuring they were created in a secure environment like *Secure Enclave*. Developers can leverage *DeviceCheck* functionality by using the framework itself.
-    These services, specifically developed by the manufacturer, are integrated within the Android or iOS SDKs, eliminating the need for a predefined endpoint to access them. Additionally, as they are specifically developed for mobile architecture, they do not need to be registered as Federation Entities through national accreditation systems.
+    These services, specifically developed by the manufacturer, are integrated within the Android or iOS SDKs, eliminating the need for a predefined endpoint to access them. Additionally, as they are specifically developed for mobile architecture, they do not need to be registered as Federation Entities through national registration systems.
     For Apple devices *Secure Enclave* is available since the iPhone 5s (2013).
     For Android devices, the inclusion of **Strongbox Keymaster** may vary by each smartphone manufacturer, who decides whether to include it or not.
 

diff --git a/docs/en/wallet-solution.rst b/docs/en/wallet-solution.rst
@@ -234,7 +234,7 @@ Below a non-normative example of the Entity Configuration.
       ]
     },
     "federation_entity": {
-      "organization_name": "IT Wallet Provider",
+      "organization_name": "IT-Wallet Provider",
       "homepage_uri": "https://wallet-provider.example.org",
       "policy_uri": "https://wallet-provider.example.org/privacy_policy",
       "tos_uri": "https://wallet-provider.example.org/info_policy",

diff --git a/docs/it/conf.py b/docs/it/conf.py
@@ -13,7 +13,6 @@
 # -- No need to change below here
 
 import sys, os
-docs_italia_theme = __import__("docs_italia_theme")
 from recommonmark.transform import AutoStructify
 from recommonmark.parser import CommonMarkParser
 
@@ -48,7 +47,7 @@
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.ifconfig',
-    'docs_italia_theme',
+    'sphinx.ext.autosectionlabel',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -111,9 +110,9 @@ def setup(app):
 
 
 # -- Options for HTML output ----------------------------------------------
-html_theme = 'docs-italia-theme'
+html_theme = 'piccolo_theme'
 
-html_theme_path = [docs_italia_theme.get_html_theme_path()]
+# html_theme_path = [docs_italia_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -130,8 +129,9 @@ def setup(app):
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
 if not on_rtd:  # only import and set the theme if we're building docs locally
-    html_theme_path = [docs_italia_theme.get_html_theme_path()]
-    html_theme = 'docs_italia_theme'
+    #  html_theme_path = [docs_italia_theme.get_html_theme_path()]
+    #  html_theme = 'docs_italia_theme'
+    pass
 else:
     # Override default css to get a larger width for ReadTheDoc build
     html_context = {
@@ -281,5 +281,5 @@ def setup(app):
 
 numfig = True
 
-# to turn smartquotes off and be able to use ’ 
+# to turn smartquotes off and be able to use  
 smartquotes = False
diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -1,28 +1,33 @@
-alabaster==0.7.12
-Babel==2.10.1
+alabaster==0.7.16
+Babel==2.15.0
 certifi==2024.7.4
-charset-normalizer==2.0.12
+charset-normalizer==3.3.2
 commonmark==0.9.1
-doc8==0.11.1
-docs-italia-theme @ git+https://github.com/italia/docs-italia-theme.git@3209d99db00ef965c528fd2932ae7da7dcee26b0
-docutils==0.18.1
+doc8==1.1.1
+docutils==0.20.1
 idna==3.7
-imagesize==1.3.0
+imagesize==1.4.1
 Jinja2==3.1.4
-MarkupSafe==2.1.1
-packaging==21.3
-Pygments==2.15.0
-pyparsing==3.0.9
-pytz==2022.1
-PyYAML==6.0
+MarkupSafe==2.1.5
+packaging==24.1
+pbr==6.0.0
+Pygments==2.18.0
+pyparsing==3.1.2
+pytz==2024.1
+PyYAML==6.0.1
 recommonmark==0.7.1
-requests==2.32.0
+requests==2.32.3
+restructuredtext-lint==1.4.0
 snowballstemmer==2.2.0
-Sphinx==5.0.1
-sphinxcontrib-applehelp==1.0.2
-sphinxcontrib-devhelp==1.0.2
-sphinxcontrib-htmlhelp==2.0.0
+Sphinx==7.4.5
+sphinx-theme==1.0
+sphinxcontrib-applehelp==1.0.8
+sphinxcontrib-devhelp==1.0.6
+sphinxcontrib-htmlhelp==2.0.5
 sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-qthelp==1.0.3
-sphinxcontrib-serializinghtml==1.1.5
-urllib3==1.26.19
+sphinxcontrib-qthelp==1.0.7
+sphinxcontrib-serializinghtml==1.1.10
+stevedore==5.2.0
+tomli==2.0.1
+urllib3==2.2.2
+piccolo_theme