Merge pull request #637 from catenax-ng/chore/#282-improve-documentat…

…ion-workflow

Chore/#282 improve documentation workflow

.github/workflows/publish-documentation.yaml

@@ -1,15 +1,18 @@
-name: Publish documentation
+name: Lint and Publish documentation
 
 on:
   workflow_dispatch: # Trigger manually
+  pull_request:
+    paths:
+      - 'docs/**'
   push:
     branches:
       - main
     paths:
       - 'docs/**'
 
 jobs:
-  publish:
+  lint-and-publish:
     # depending on default permission settings for your org (contents being read-only or read-write for workloads), you will have to add permissions
     # see: https://docs.github.com/en/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token
     permissions:
@@ -64,6 +67,12 @@ jobs:
             asciidoctor-reducer -o docs/target/adminguide.adoc docs/src/docs/administration/administration-guide.adoc
             asciidoctor-reducer -o docs/target/arc42.adoc docs/src/docs/arc42/full.adoc
 
+      - name: Cache plantuml jar
+        uses: actions/cache@v3
+        with:
+          path: plantuml.jar
+          key: ${{ runner.os }}-file-${{ hashFiles('plantuml.jar') }}
+
       - name: Download PlantUML jar
         run: |
           wget -O plantuml.jar https://sourceforge.net/projects/plantuml/files/plantuml.jar/download
@@ -103,7 +112,8 @@ jobs:
         run: |
           mv docs/src/diagram-replacer/assets/ docs/target/generated-docs/assets/
 
-      - name: GitHub Pages action
+      - name: Update documentation on GitHub Pages
+        if: github.ref == 'refs/heads/main'
         uses: peaceiris/actions-gh-pages@v3.9.3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}

docs/src/docs/arc42/building-block-view/whitebox-overall.adoc

@@ -50,19 +50,19 @@ include::../../../uml-diagrams/building-block-view/whitebox_overall_decentral.pu
 |Number |Description
 
 | 01
-| IrsApiConsumer calls the **IRS** public **API**
+| IrsApiConsumer calls the *IRS* public *API*
 
 | 02
-| IrsApiConsumer must authorize using **technical C-X User**
+| IrsApiConsumer must authorize using *technical C-X User*
 
 | 03
-| Delegate authorization request to **IdP**
+| Delegate authorization request to *IdP*
 
 | 04
-| IRS requesting for **SubmodelAspects** using **EDC**
+| IRS requesting for *SubmodelAspects* using *EDC*
 
 | 05
-| IRS requesting the **decentral DigitalTwinRegistry** over **EDC** and service discovery flow
+| IRS requesting the *decentral DigitalTwinRegistry* over *EDC* and service discovery flow
 
 | 06
 | IRS uses EDC to ensure sovereign data consumption
@@ -71,31 +71,31 @@ include::../../../uml-diagrams/building-block-view/whitebox_overall_decentral.pu
 | IRS MUST authorize at central IAM
 
 | 08
-| IRS lookup for EDC Provider by given BPNs over the **EDC Discovery Service**
+| IRS lookup for EDC Provider by given BPNs over the *EDC Discovery Service*
 
 | 09
-| IRS lookup for **EDC Discovery Services** by given type <BPN> over the **Discovery Finder**
+| IRS lookup for *EDC Discovery Services* by given type <BPN> over the *Discovery Finder*
 
 | 10
-| IRS uses **Semantic Hub** to validate of **SubmodelAspects** payloads agains the schema provided in **Semantic Hub**
+| IRS uses *Semantic Hub* to validate of *SubmodelAspects* payloads agains the schema provided in *Semantic Hub*
 
 | 11
 | In case "lookupBPNs" is active IRS provides a lookup of company for given BPN
 
 | 12
-| **EDC** is connected to **Managed Identity Wallet** for access policy check for data offers
+| *EDC* is connected to *Managed Identity Wallet* for access policy check for data offers
 
 | 13
-| **EDC** communication covering negotiation and data consumption
+| *EDC* communication covering negotiation and data consumption
 
 | 14
-| **EDC** is connected to **Managed Identity Wallet** for access policy check for data offers
+| *EDC* is connected to *Managed Identity Wallet* for access policy check for data offers
 
 | 15
-| **IRS** accessing to **SubmodelServer** on Tier Level using the **EDC**
+| *IRS* accessing to *SubmodelServer* on Tier Level using the *EDC*
 
 | 16
-| **IRS** accessing the **decentral DigitalTwinRegistry** on Tier Level using the **EDC**
+| *IRS* accessing the *decentral DigitalTwinRegistry* on Tier Level using the *EDC*
 |===
 
 

docs/src/docs/arc42/cross-cutting/safety-security.adoc

@@ -11,7 +11,7 @@ JWT token should also contain two claims:
 - 'bpn' which is equal to the configuration value from `API_ALLOWED_BPN` property
 - 'resource_access' with the specific 'Cl20-CX-IRS' key for C-X environments. (The keys are configurable. For more details see chapter "IRS OAuth2 JWT Token").
 The list of values will be converted to roles by IRS.
-Currently, IRS API handles two roles: **'admin_irs'** and **'view_irs'.** A valid token with the **'admin_irs'** role can access any endpoint exposed by the IRS API, while a token with the **'view_irs'** role does not have access to policies endpoints and can operate only on resources it owns.
+Currently, IRS API handles two roles: *'admin_irs'* and *'view_irs'.* A valid token with the *'admin_irs'* role can access any endpoint exposed by the IRS API, while a token with the *'view_irs'* role does not have access to policies endpoints and can operate only on resources it owns.
 That means that he only has access to the resources he has created, e.g. jobs and batches.
 This behavior is shown in the table below.
 

docs/src/docs/arc42/runtime-view/ess-top-down/ess-top-down.adoc

@@ -54,7 +54,7 @@ Note: ESS supplier responses are involved in each step of the process.
 include::../../../../uml-diagrams/runtime-view/use-case-ess-top-down/1_ess-top-down-sequence-highlevel.puml[]
 ....
 
-=== Step 0: Process initiation:
+=== Step 0: Process initiation
 
 The process is initiated by an ESS incident, that is received by (or created within) the inquiring company.
 This ESS incident acts as the root incident for the overall process The incident contains a company name (incl. address) and a valid BPN exists for that company.