Merge pull request #114 from asam-ev/add_asam-antora-extensions

Add asam antora extensions

.antora/modules/specification/nav-openmaterial.adoc

@@ -1,5 +1,12 @@
+
+//Deprecated, use 'OpenMATERIAL/content/nav-openmaterial.adoc' instead.
+
+//But keep this file here, since it is necessary for the asam-antora-extension pipeline!
+
 * xref:general-docs/foreword.adoc[]
 * xref:general-docs/introduction.adoc[]
+
+////
 * xref:general-docs/scope.adoc[]
 * xref:general-docs/normative-references.adoc[]
 * xref:general-docs/abbreviations.adoc[]

.github/workflows/antora-build.yml

@@ -17,16 +17,60 @@ permissions:
   id-token: write
 jobs:
   build:
+    name: Build OpenMATERIAL documentation and deploy it to gh-pages
     runs-on: ubuntu-latest
+    services:
+      kroki:
+        image: yuzutech/kroki:0.15.1
+        env:
+          KROKI_MAX_URI_LENGTH: 8000
+          KROKI_BLOCKDIAG_HOST: blockdiag
+          KROKI_MERMAID_HOST: mermaid
+      blockdiag:
+        image: yuzutech/kroki-blockdiag:0.15.1
+      mermaid:
+        image: yuzutech/kroki-mermaid:0.15.1
+
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
-    - name: Checkout repository
+    - name: Checkout with submodules
       uses: actions/checkout@v4
+      with:
+         path: repo
+         fetch-depth: 0 # test if depth in fetch history is required
+         submodules: recursive
+
+    - name: Checkout documentation
+      if: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.head_ref }}
+      uses: actions/checkout@v4
+      with:
+        repository: asam-ev/OpenMATERIAL
+        path: repo #osi-documentation
+        fetch-depth: 0 # test if depth in fetch history is required
+
+    - name: Apply dispatch information
+      if: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.head_ref }}
+      working-directory: repo
+      run: |
+        SRC=${{ github.event.client_payload.src }}
+        IFS="/"
+        SRC_REPO=($SRC)
+        unset IFS
+        SRC_REPO=${SRC_REPO[1]}
+        HEAD_REF=${{ github.event.client_payload.head_ref }}
+        echo Branch build for ${HEAD_REF} in ${SRC_REPO}
+        sed -i -r "s|\[(.*)\] # o|[\1,HEAD] # ${SRC_REPO} # o|g" site.yml
+        sed -i -r "s|(- url: .*# retrieve content from remote)|# \1|g" site.yml
+        sed -i -r "s|# (- url: .*# retrieve content locally)|\1|g" site.yml
+        echo Checking out the target branch
+        cd OpenMATERIAL
+        git checkout ${HEAD_REF} 2>/dev/null || git checkout -b ${HEAD_REF}
+        cd ..
 
     - name: Generate AsciiDoc from JSON
-      working-directory: scripts
+      working-directory: repo/scripts
       run: |
         python3 json2asciidoc.py ../schemas/asset_schema.json metadata
         mv metadata.adoc ../content/geometry/
@@ -40,22 +84,42 @@ jobs:
     - name: Configure Pages
       uses: actions/configure-pages@v4
 
-    - name: Install Node.js
-      uses: actions/setup-node@v4
+    - name: Generate site
+      uses: docker://ghcr.io/asam-ev/project-guide-docker:4
       with:
-        node-version: '20'
+        entrypoint: sh
+        args: repo/run-build.sh # modfied based on OSI
 
-    - name: Install Antora
-      run: npm i antora
-
-    - name: Generate Site
-      run: npx antora antora-playbook.yml
+
 
     - name: Upload Artifacts
       uses: actions/upload-pages-artifact@v3
       with:
-        path: build/site
+        path: ./repo/site
+
+  deploy:
+    # Run if it was not triggered from remote OR the remote source was master or main.
+    if: ${{ github.event_name != 'repository_dispatch' || contains(github.event.client_payload.ref, 'master') || contains(github.event.client_payload.ref, 'main') }}
+    # Allow one concurrent deployment
+    concurrency:
+      group: "pages"
+      cancel-in-progress: true
+
+    needs: build
+    permissions:
+      actions: read
+      pages: write
+      id-token: write
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4
 
-    - name: Deploy to GitHub Pages
-      id: deployment
-      uses: actions/deploy-pages@v4

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "asam-antora-extensions"]
+	path = asam-antora-extensions
+	url = https://code.asam.net/common/asam-antora-extensions

antora-playbook.yml

@@ -28,7 +28,44 @@ ui:
 
 output:
   clean: true
-  dir: ./build/site
-
+  dir: ./site
 runtime:
   fetch: true
+
+# tag::attributes[]
+asciidoc:
+  attributes:
+    page-pagination: true
+    hide-uri-scheme: ""
+    kroki-server-url: 'http://kroki:8000'
+    kroki-fetch-diagram: ""
+    # Allow URI read to retrieve SVG on compilation
+    allow-uri-read: true
+    # use SVG unless otherwise specified
+    kroki-default-format: svg
+    # Make SVG inline so that we can get interactive (can be overridden by schema with "opts=none")
+    kroki-default-options: interactive
+    sectnums: "@"
+    xrefstyle: short@
+    listing-caption: Code
+    page-width-limit: none@
+    THIS_STANDARD: ASAM OpenMATERIAL
+
+
+# end::attributes[]
+
+  extensions:
+  - asciidoctor-kroki
+  - './asam-antora-extensions/asam-asciidoctor_extensions.js'
+  - './asam-antora-extensions/asam-asciidoctor_extensions-registered.js'
+
+antora:
+  extensions:
+    - require: '@antora/lunr-extension'
+    - require: './asam-antora-extensions/asam-antora_extension.js'
+      numbered_titles: true
+      section_number_style: 'iso'
+      alternate_xref_style: 'full'
+      loft: true
+      local_to_global_references: false
+      bibliography: false

content/geometry/geometry-index.adoc

@@ -1,9 +1,9 @@
 = Geometry
 
-include::Introduction.adoc[leveloffset=+1]
-include::General.adoc[leveloffset=+1]
-include::object-classes.adoc[leveloffset=+1]
-include::File_format_support.adoc[leveloffset=+1]
-include::metadata.adoc[leveloffset=+1]
-include::Performance.adoc[leveloffset=+1]
+* xref:geometry/introduction.adoc[leveloffset=+1]
+* xref:geometry/general.adoc[leveloffset=+1]
+* xref:geometry/object-classes.adoc[leveloffset=+1]
+* xref:geometry/file-format-support.adoc[leveloffset=+1]
+* xref:geometry/metadata.adoc[leveloffset=+1]
+* xref:geometry/performance.adoc[leveloffset=+1]
 

content/index.adoc

@@ -21,7 +21,6 @@ In alteration to the regular https://www.asam.net/license[license terms], ASAM a
 // DO NOT CHANGE!!!
 
 
-:antora_mapping: true
 ifndef::use-antora-rules[]
 
 [preface]
@@ -66,5 +65,4 @@ include::loft/list-of-figures.adoc[leveloffset=+1]
 
 :sectnums!:
 include::loft/list-of-tables.adoc[leveloffset=+1]
-endif::[]
-:!antora_mapping:
+endif::[]

content/material/material-index.adoc

@@ -1,7 +1,7 @@
 = Material
 
-include::Introduction.adoc[leveloffset=+1]
-include::Fileformat.adoc[leveloffset=+1]
-include::metadata.adoc[leveloffset=+1]
-include::material-properties.adoc[leveloffset=+1]
-include::lookup-tables.adoc[leveloffset=+1]
+* xref:material/introduction.adoc[leveloffset=+1]
+* xref:material/fileformat.adoc[leveloffset=+1]
+* xref:material/metadata.adoc[leveloffset=+1]
+* xref:material/material-properties.adoc[leveloffset=+1]
+* xref:material/lookup-tables.adoc[leveloffset=+1]

content/nav-openmaterial.adoc

@@ -0,0 +1,48 @@
+:sectnums!:
+
+:antora_mapping: true
+
+[preface]
+* xref:../general-docs/foreword.adoc[]
+[preface]
+* xref:../general-docs/introduction.adoc[]
+
+:sectnums:
+* xref:general-docs/scope.adoc[]
+* xref:general-docs/normative-references.adoc[]
+* xref:general-docs/abbreviations.adoc[]
+* xref:general-docs/backward-compatibility.adoc[]
+* xref:terms-and-definitions/terms-and-definitions.adoc[]
+* xref:use-cases/use-cases.adoc[]
+* xref:geometry/geometry-index.adoc[]
+** xref:geometry/introduction.adoc[]
+** xref:geometry/general.adoc[]
+** xref:geometry/object-classes.adoc[]
+** xref:geometry/file-format-support.adoc[]
+** xref:geometry/metadata.adoc[]
+** xref:geometry/performance.adoc[]
+* xref:material/material-index.adoc[]
+** xref:material/introduction.adoc[]
+** xref:material/file-format.adoc[]
+** xref:material/metadata.adoc[]
+** xref:material/material-properties.adoc[Material properties]
+** xref:material/lookup-tables.adoc[]
+
+
+
+:sectnums!:
+== Annexes
+[appendix]
+//include::annexes/REPLACE_ME.adoc[leveloffset=+2]
+// Add  further annexes here as needed and replace the placeholder one above
+
+[bibliography]
+include::bibliography.adoc[leveloffset=+1]
+
+:sectnums!:
+include::loft/list-of-figures.adoc[leveloffset=+1]
+
+:sectnums!:
+include::loft/list-of-tables.adoc[leveloffset=+1]
+
+:!antora_mapping:

run-build.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+# This script is used tackle a some specifics of the GitHub action used with a docker container. 
+# It copies the cached node-modules from the container to the runner workspace and then triggers the build using npm
+
+cp -r /usr/src/repo/. /github/workspace/.
+cd repo
+export NODE_OPTIONS="--max-old-space-size=8192"
+exec antora --stacktrace --fetch --clean antora-playbook.yml