diff --git a/.github/workflows/site-build.yml b/.github/workflows/site-build.yml new file mode 100644 index 0000000..4a4db5e --- /dev/null +++ b/.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:$ASAM_ANTORA_EXTENSIONS@code.asam.net/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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..6b2265c --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +*.html +public/ +*.pyc +.vscode/settings.json +ui-bundle/ +checked_out_content_repo/ +test/ +site_local.yml \ No newline at end of file diff --git a/.gitlab-ci.yml.txt b/.gitlab-ci.yml.txt new file mode 100644 index 0000000..bdd6da7 --- /dev/null +++ b/.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 "pipeline@asam.net" + - 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:$PUBLICATION_ACCESS_TOKEN@code.asam.net/$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:$PUBLICATION_ACCESS_TOKEN@code.asam.net/$EXTERNAL_REPO_URL" + - git add . + - git commit -m "Updated ${PROJECT_NAME}" + - git push origin HEAD:main + needs: + - job: antora_build_release + artifacts: true diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..f665c86 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "asam-antora-extensions"] + path = asam-antora-extensions + url = https://code.asam.net/common/asam-antora-extensions diff --git a/README.md b/README.md index b51d889..c430dfa 100644 --- a/README.md +++ b/README.md @@ -1 +1,6 @@ -# openmaterial-antora-generator \ No newline at end of file +# 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 . + diff --git a/asam-antora-extensions b/asam-antora-extensions new file mode 160000 index 0000000..6eb710a --- /dev/null +++ b/asam-antora-extensions @@ -0,0 +1 @@ +Subproject commit 6eb710a0aa0714a3cc84827e3c00f2ba6abb0e13 diff --git a/docker-compose-local.yml b/docker-compose-local.yml new file mode 100644 index 0000000..711f463 --- /dev/null +++ b/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 diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..e3699e5 --- /dev/null +++ b/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 diff --git a/package.json b/package.json new file mode 100644 index 0000000..438d1f8 --- /dev/null +++ b/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" + } + } diff --git a/repo_images/Generator_icon.drawio b/repo_images/Generator_icon.drawio new file mode 100644 index 0000000..ad2eea1 --- /dev/null +++ b/repo_images/Generator_icon.drawio @@ -0,0 +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= \ No newline at end of file diff --git a/repo_images/Generator_icon.png b/repo_images/Generator_icon.png new file mode 100644 index 0000000..c065caf Binary files /dev/null and b/repo_images/Generator_icon.png differ diff --git a/repo_images/Generator_icon.svg b/repo_images/Generator_icon.svg new file mode 100644 index 0000000..617f7e5 --- /dev/null +++ b/repo_images/Generator_icon.svg @@ -0,0 +1,3 @@ + + +
A
AText is not SVG - cannot display \ No newline at end of file diff --git a/repo_images/Pipeline.drawio.svg b/repo_images/Pipeline.drawio.svg new file mode 100644 index 0000000..31efc0e --- /dev/null +++ b/repo_images/Pipeline.drawio.svg @@ -0,0 +1,514 @@ + + + + + + + + +
+
+
+ Change made +
+ || Manual trigger +
+
+
+ + + Change made... + + + + + + + +
+
+
+ Generator repository (this) +
+
+
+ + + Generator reposi... + + + + + + + + +
+
+
+ Trigger +
+
+
+ + + Trigger + + + + + + + +
+
+
+ Component repository +
+
+
+ + + Component reposi... + + + + + + + + + +
+
+
+ Run Antora +
+
+
+ + + Run Antora + + + + + + + + + +
+
+
+ Done +
+
+
+ + + Done + + + + + + + + + LEGEND + + + + + + +
+
+
+ Start +
+
+
+ + + Start + + + + + + + +
+
+
+ End +
+
+
+ + + End + + + + + + + +
+
+
+ decision +
+
+
+ + + decision + + + + + + + +
+
+
+ Default +
+
+
+ + + Default + + + + + + + +
+
+
+ Merge Request +
+
+
+ + + Merge Re... + + + + + + + +
+
+
+ Release +
+
+
+ + + Release + + + + + + + + +
+
+
+ Yes +
+
+
+ + + Yes + + + + + + + + +
+
+
+ No +
+
+
+ + + No + + + + + + + +
+
+
+ Var "TAGGED_ +
+ RELEASE" set? +
+
+
+ + + Var "TAGGED_... + + + + + + + + + +
+
+
+ Prepare site.yml for release version and ALGOLIA search +
+
+
+ + + Prepare site.yml... + + + + + + + + + +
+
+
+ Run Antora for release (with ALGOLIA search) +
+
+
+ + + Run Antora for r... + + + + + + + + + +
+
+
+ Prepare site.yml for source branch +
+
+
+ + + Prepare site.yml... + + + + + + + + +
+
+
+ Yes +
+
+
+ + + Yes + + + + + + + + +
+
+
+ No +
+
+
+ + + No + + + + + + + +
+
+
+ Triggered by +
+ Merge Request on component repository? +
+
+
+ + + Triggered by... + + + + + + + + + +
+
+
+ Run Antora +
+
+
+ + + Run Antora + + + + + + + +
+
+
+ Update +
+ Pages +
+
+
+ + + Update... + + + + + + + + +
+
+
+ Yes +
+
+
+ + + Yes + + + + + + + + +
+
+
+ No +
+
+
+ + + No + + + + + + + +
+
+
+ Default branch +
+ OR triggered by content +
+ repository? +
+
+
+ + + Default branch... + + + + + + + + + +
+
+
+ Publish to publication repository +
+
+
+ + + Publish to publi... + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/run-build.sh b/run-build.sh new file mode 100644 index 0000000..ff0d464 --- /dev/null +++ b/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 site.yml diff --git a/scripts/build.py b/scripts/build.py new file mode 100644 index 0000000..c70d383 --- /dev/null +++ b/scripts/build.py @@ -0,0 +1,69 @@ +from ast import AsyncFunctionDef +import os,sys,getopt + +def main(argv): + parameters="sfr" + parameters_long = ["start","finish", "remote"] + + do_start = False + do_finish = False + do_test = False + do_remote = False + + try: + opts, args = getopt.getopt(argv,parameters,parameters_long) + except: + print("Optional parameters are: -s, --start, -f, --finish, -r, --remote") + + for opt,arg in opts: + if opt in ("-s","--start"): + do_start = True + + elif opt in ("-f","--finish"): + do_finish = True + do_clean = True + elif opt in ("-r","--remote"): + do_remote = True + + if not (do_start or do_finish): + do_start = do_finish = True + + if do_start: + if (do_remote): + run_docker_compose(True) + else: + run_docker_compose() + + if do_finish: + open_project_guide() + print("BUILD DONE") + +def run_docker_compose(remote_setup=False): + if (remote_setup): + target = "docker-compose" + else: + target = "docker-compose -f docker-compose-local.yml" + print("RUN DOCKER-COMPOSE WITH " + target) + try: + os.chdir("../") + os.system(target+" run antora") + except: + try: + os.system(target+" run antora") + except: + pass + +def open_project_guide(): + print("OPEN INDEX.HTML") + try: + os.chdir("../site") + # print(os.getcwd()) + os.system("start chrome {pos}".format(pos = os.getcwd()+"/index.html")) + except: + try: + os.system("start chrome {pos}".format(pos = os.getcwd()+"/index.html")) + except: + pass + +if __name__ == "__main__": + main(sys.argv[1:]) \ No newline at end of file diff --git a/site.yml b/site.yml new file mode 100644 index 0000000..26c1575 --- /dev/null +++ b/site.yml @@ -0,0 +1,74 @@ +# tag::site[] +site: + title: ASAM OpenMATERIAL # This is how the overall Antora instance will be named. + # the 404 page and sitemap files only get generated when the url property is set + url: https://asam-ev.github.io/openmaterial-antora-generator/asamopenmaterial/latest/specification/ + start_page: asamopenmaterial:specification:index.adoc +# end::site[] +urls: # Creates a redirect for the newest version to the link "latest" + latest_version_segment_strategy: redirect:to + latest_version_segment: latest + +# tag::content[] +content: + sources: + - url: https://github.com/asam-ev/OpenMATERIAL.git # <1> + branches: [main, v*.*.*] + tags: [v*,V*] + start_path: .antora + # edit_url: 'https://code.asam.net/internal/examples/antora-content-base-structure/-/blob/{refname}/{path}' + - url: https://code.asam.net/common/asam-terminology.git # <2> + start_path: .antora + tags: [v*,V*] +# end::content[] + +ui: + bundle: + url: https://code.asam.net/common/antora-ui/-/jobs/artifacts/main/raw/build/ui-bundle.zip?job=bundle-stable + snapshot: true + # supplemental_files: ./supplemental_ui # Activate this if you need to make local UI changes. Check the official Antora documentation for more information. + +output: + clean: true + 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 # Orignal value: true + bibliography: false # Original value: true; deactivated because build failed +