Merge pull request #1 from asam-ev/antora-generator

Move Antora generator configuration to main branch

.github/workflows/site-build.yml

@@ -0,0 +1,109 @@
+name: ASAM OpenMATERIAL build
+# Based on https://github.com/OpenSimulationInterface/osi-antora-generator/blob/main/.github/workflows/site-build.yml
+
+on:
+  push: # on push
+    branches: [ main, antora-generator ] # External workflow only triggers default branch
+  # schedule: # periodic - needed because some of the content is from the other repos
+  #   - cron:  '30 5,20 * * *' # twice per day, in the morning and evening.
+  repository_dispatch:
+    types: [antora-build-trigger] 
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build OpenMATERIAL documentation and deploy it to GitHub pages
+    runs-on: ubuntu-20.04
+
+    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
+
+    steps:
+
+    # checkout repo into folder guide. This is done to match the setup for the local build in docker-compose
+    - 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: Submodules
+    #   working-directory: repo
+    #   env: 
+    #     ASAM_ANTORA_EXTENSIONS: ${{ secrets.ASAM_ANTORA_EXTENSIONS }}
+    #   run: git clone --recurse-submodules https://asam-antora-extensions:[email protected]/common/asam-antora-extensions.git
+
+    - 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/OpenMATERIAL 
+        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 ..
+ 
+    # build site
+    - name: Generate site
+      uses: docker://ghcr.io/asam-ev/project-guide-docker:4
+      with:
+        entrypoint: sh
+        args: repo/run-build.sh
+
+    - name: Upload pages artifact
+      uses: actions/upload-pages-artifact@v3
+      with: 
+        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

.gitignore

@@ -0,0 +1,8 @@
+*.html
+public/
+*.pyc
+.vscode/settings.json
+ui-bundle/
+checked_out_content_repo/
+test/
+site_local.yml

.gitlab-ci.yml.txt

@@ -0,0 +1,127 @@
+# Cache docker images
+cache:
+  key: one-key-to-rule-them-all
+
+stages:
+  - build
+  - upload
+  - publish
+
+variables:              # Define a set of global variables for the pipeline
+  GIT_SUBMODULE_STRATEGY: normal
+  GIT_CREDENTIALS: "https://gitlab-ci-token:${CI_JOB_TOKEN}@code.asam.net"
+  EXTERNAL_REPO_URL: publications/standards.git
+  KROKI_MAX_URI_LENGTH: 20000
+  KROKI_BLOCKDIAG_HOST: blockdiag
+  KROKI_MERMAID_HOST: mermaid
+  PROJECT_NAME: ASAM_PLACEHOLDER
+
+antora_build_release:   # Build Antora when triggered by a tag in one of its source repos (upstream)
+  stage: build
+  image:
+    name: ghcr.io/asam-ev/project-guide-docker:4
+    entrypoint: [""]
+  # services:
+  #   - name: yuzutech/kroki
+  #     alias: kroki
+  tags:
+    - asciidoc
+  rules:
+    - if: $TAGGED_RELEASE
+    - when: never
+  variables:
+    SITE_SEARCH_PROVIDER: ALGOLIA
+    ALGOLIA_APP_ID: H1VJQITG6C
+    ALGOLIA_READ_API_KEY: 75a02201dd40dc09ae80f060056cfe79
+    ALGOLIA_INDEX_NAME: publications-pages-asam
+  script:
+    # For a tagged release to build only tagged content, the site.yml needs to be updated. Each content must explicitly exclude branches so that the default branch and such are not included in the build.
+    # Also, the search engine is switched from lunr to algolia for the output
+    - |
+      sed -i 's/branches: \[main, v*.*.*\]/branches: [v*.*.*]/g' site.yml
+      sed -i 's/branches: \[main\]/branches: ~/g' site.yml
+      sed -i "s|- require: '@antora/lunr-extension'||g" site.yml
+      sed -i -E 's/edit_url:(.*)/# edit_url:\1/g' site.yml
+    - cat site.yml
+    # Build Antora
+    - antora --stacktrace --fetch --clean site.yml
+  artifacts:
+    expose_as: 'antora_build'
+    paths:
+      - public/
+
+antora_build:          # Build Antora when not triggered by a release upstream.
+  stage: build
+  image:
+    name: ghcr.io/asam-ev/project-guide-docker:4
+    entrypoint: [""]
+  # services:
+  #   - name: yuzutech/kroki
+  #     alias: kroki
+  tags:
+    - asciidoc
+  rules:
+    - if: $TAGGED_RELEASE
+      when: never
+    - if: $CI_PIPELINE_SOURCE == 'trigger'
+    - if: $CI_PIPELINE_SOURCE == 'pipeline'
+    - if: $CI_PIPELINE_SOURCE == 'push'
+  script:
+    # If this job was triggered by a push to an upstream repo on a non-default branch, update the site.yml to include that branch instead of the default one.
+    # This allows the changes to be viewed in the respective Merge Request.
+    - |
+      if [[ $UPSTREAM_BRANCH ]]; then
+        echo "Replacing branch for ${UPSTREAM_REPO} with ${UPSTREAM_BRANCH}"
+        sed -r -i '\|- url: '"$UPSTREAM_REPO"'|{ n; s|(branches: )\[main, v*.*.*\]|\1[main, '"$UPSTREAM_BRANCH"', v*.*.*]| }' site.yml
+      fi
+    # Build Antora
+    - antora --stacktrace --fetch --clean site.yml
+  artifacts:
+    expose_as: 'antora_build'
+    paths:
+      - public/
+
+pages:                # Publish the built Antora output to GitLab pages. Runs only if triggered by a change to the generator or a push to the default branch in an upstream repo.
+  stage: upload
+  image: busybox
+  tags:
+    - asciidoc
+  rules:
+    - if: $TAGGED_RELEASE
+      when: never
+    - if: $UPSTREAM_BRANCH
+      when: never
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+    - if: $CI_PIPELINE_SOURCE == 'trigger'
+  script:
+    - echo "The site will be deployed to $CI_PAGES_URL"
+  artifacts:
+    paths:
+      - public
+
+publish:              # If this pipeline was triggereed by a tagged release in an upstream repository, push the output to the publication group.
+                      # This is where all ASAM release will be automatically hosted through GitLab.
+  stage: publish
+  tags:
+    - asciidoc
+  rules:
+    - if: $TAGGED_RELEASE
+  before_script:
+    - git config --global user.email "[email protected]"
+    - git config --global user.name "GitLab Pipeline"
+  script:
+    - echo "Publishing the generated pages"
+    - echo "The created Antora output is pushed to publications/standards"
+    # Clone the publication repo and remove the current content for this project, then copy the new content and commit/push to the downstream repo
+    - git clone https://PUBLICATION_ACCESS_TOKEN:[email protected]/$EXTERNAL_REPO_URL downstream_repo
+    - rm -rf downstream_repo/public/${PROJECT_NAME}
+    - cp -R site downstream_repo/public/${PROJECT_NAME}
+    - cd downstream_repo
+    - git remote rm origin
+    - git remote add origin "https://PUBLICATION_ACCESS_TOKEN:[email protected]/$EXTERNAL_REPO_URL"
+    - git add .
+    - git commit -m "Updated ${PROJECT_NAME}"
+    - git push origin HEAD:main
+  needs:
+    - job: antora_build_release
+      artifacts: true

.gitmodules

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

README.md

@@ -1 +1,6 @@
-# openmaterial-antora-generator
+# OpenMATERIAL Antora Generator
+
+This is the Antora configuration for the OpenMATERIAL project. It is based on the [Antora Generator Template](https://code.asam.net/common/templates/antora-base-repo-example). 
+
+The output is published  at <https://asam-ev.github.io/openmaterial-antora-generator/asamopenmaterial/latest/specification/>.
+

docker-compose-local.yml

@@ -0,0 +1,28 @@
+version: "2"
+
+services:
+
+  antora:
+    image: ghcr.io/asam-ev/project-guide-docker:4
+    volumes:
+      - .:/usr/src/repo #has to match WORKSPACE defined in Dockerfile + folder from package.json "docker-build"
+    depends_on:
+      - kroki
+      - blockdiag
+      - mermaid
+    entrypoint: antora --stacktrace --fetch --clean site_local.yml
+    # entrypoint: /bin/bash
+
+
+  kroki:
+    image: yuzutech/kroki:0.15.1
+    environment:
+      - KROKI_MAX_URI_LENGTH=20000
+      - KROKI_BLOCKDIAG_HOST=blockdiag
+      - KROKI_MERMAID_HOST=mermaid
+
+  blockdiag:
+    image: yuzutech/kroki-blockdiag:0.15.1
+
+  mermaid:
+    image: yuzutech/kroki-mermaid:0.15.1

docker-compose.yml

@@ -0,0 +1,28 @@
+version: "2"
+
+services:
+
+  antora:
+    image: ghcr.io/asam-ev/project-guide-docker:4
+    volumes:
+      - .:/usr/src/repo #has to match WORKSPACE defined in Dockerfile + folder from package.json "docker-build"
+    depends_on:
+      - kroki
+      - blockdiag
+      - mermaid
+    entrypoint: antora --stacktrace --fetch --clean site.yml
+    # entrypoint: /bin/bash
+
+
+  kroki:
+    image: yuzutech/kroki:0.15.1
+    environment:
+      - KROKI_MAX_URI_LENGTH=20000
+      - KROKI_BLOCKDIAG_HOST=blockdiag
+      - KROKI_MERMAID_HOST=mermaid
+
+  blockdiag:
+    image: yuzutech/kroki-blockdiag:0.15.1
+
+  mermaid:
+    image: yuzutech/kroki-mermaid:0.15.1

package.json

@@ -0,0 +1,17 @@
+{
+    "private": true,
+   "scripts": {
+     "clean-build": "npm run clean-install;npm run build",
+     "clean-install": "rm -rf node_modules/ .cache/ package-lock.json ;npm run plain-install",
+     "plain-install": "npm i --cache=.cache/npm --no-optional",
+     "docker-build": "npm run plain-install; antora site.yml --stacktrace --fetch --clean",
+     "build": "antora site.yml --stacktrace --fetch --clean"
+   },
+   "devDependencies": {
+     "@antora/cli": "^3.0.0-beta.2",
+     "@antora/site-generator-default": "^3.0.0-beta.2",
+     "asciidoctor-kroki": "^0.14.0",
+     "@antora/antora-lunr-extension": "https://gitlab.com/antora/antora-lunr-extension",
+     "@djencks/asciidoctor-mathjax": "^0.0.7"
+   }
+ }

repo_images/Generator_icon.drawio

@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2022-02-10T12:12:22.611Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/16.5.1 Chrome/96.0.4664.110 Electron/16.0.7 Safari/537.36" etag="1D6QqPDqj_4npLj7tru1" version="16.5.1" type="device"><diagram id="bUCgp1hQYpNEF6TeKGY_" name="Page-1">5Zpdc6IwFIZ/DZedyQdEvRRbd2dn9qqz02tWUsg0EBrjavvrN0AQKLGVFtS2Xlg4SUjynPecJFgHL5LdDxlk8W8RUu4gEO4cfO0gRIinv3PDU2nAM1waIsnC0gRrwy17psYIjHXDQrpuVVRCcMWytnEl0pSuVMsWSCm27Wr3grd7zYKIdgy3q4B3rXcsVHFpnaJJbf9JWRRXPUMyK0uSoKpsZrKOg1BsGyZ84+CFFEKVV8luQXnOruJStlseKN0PTNJUHdNAQPi4vNtK+OdXwn3ff54tF1eu8ca/gG/MjM1o1VOFQIpNGtL8KdDB/jZmit5mwSov3Wqfa1usEm6K10qKB7oQXMiiNV4Wn31JBdHTlnvGeaMmAORmrrH4kQxCpmdVlaUi1Z35ZqRUKro7yADuyWpFUpFQJZ90FdMAISNHo0YEzP229q1r/BU33EqMLTBqivZProHrC8O8B3/svc0/0g7IDk7eCD/4W1UHfaG4ALSgYIA6UJAFChoNChlYlD2F1tawMQZyZbITmh0rxldc3vXG2WhP+tAGp6F9crxwNLzu+SMckcmFRTj60hHuXliE91rkLz/C34d3tAiHA2u51qH36obqXV5o7r+G2FC57b0DnIBuZoE2b+DR1D47NuH2VebHEzHGL3B5XVzQJt7JWLQq/11GJm7Kuw6D6fvV+4pCuk4yTtkzaTrFquHRUopn2zQQrnK+Qs+t6R7yuBFVwdW6IDbXFQjIdnVhod6KcW3E98WnaSJR/ndedaeHX/ZY2jva0PDVi/TFWZTq65V2AtUd+rmLmD5Rz01BwsIwb+5LqodroilfdTLBUlWg9HzHu86ftVGinJLlcGkU1BRcZdIjbi7lxb0ZMxxeN1UubJ8tuydLYtGQN1pg91qW+i/6+zgdfNF/I4WiFykUWqIVW0iPtuC4R5zhP/AO5eDy3dMhQ6z2BLXZzyyrvWcR+Vjkh35R8GnII3Bm8r1eGnwp8pZ8c1Ly029LHp+Z/BEHiy9K3rIjPiV5b+hDyuchbzkgnpT80C83Pg950t3An5Q8+rbkJ2cmP+5vopdMfjoWeX1b/9JdlDX+XQDf/Ac=</diagram></mxfile>