Build: Create base Antora setup

.antora/antora.yml

@@ -0,0 +1,54 @@
+# Component name (without spaces!). All content repositories with the same component name are merged in Antora.
+name: asamosi
+# CENTRAL DOCUMENT ONLY!!! Display name of the component. Define only once per component!
+title: ASAM OSI
+version:
+  # Update version number accordingly. This is the version for the main branch
+  main: 'current'
+  v(*)-antora: V$1
+  v(*): V$1
+  V(*): V$1
+  # Update version number accordingly. This is the version for any other activated branch (branch must be added in the generator site.yml!). Schema = 0.0.x-<branch-name> (only works for branches starting with "feature/")
+  (*): 'V3.6.0-$1'
+# CENTRAL DOCUMENT ONLY!!! First page of the component. Define only once per component!
+start_page: specification:index.adoc
+
+# THE FOLLOWING MAY ONLY DEFINED FOR THE CENTRAL DOCUMENT!!!
+asciidoc: # Sets global AsciiDoc attributes that are applied for every page of this component (from all repositories with the same version and component name!)
+  attributes:
+  # START - Mandatory ASAM attributes
+    use-antora-rules: true
+    THIS_STANDARD: ASAM OSI<sup>®</sup> # Normal attribute
+    THIS_STANDARD_TITLE: 'ASAM OSI^®^' # Normal attribute
+    # THIS_STANDARD: ASAM OSI # PDF version attribute
+    # THIS_STANDARD_TITLE: 'ASAM OSI' # PDF version attribute
+    partials-path: partial$
+    root-path: page$
+    appendix-caption: Annex
+    # appendix-offset: 1
+    asam-terminology: v0.0.1@ASAM_Terminology:ROOT:partial$terms_and_definitions_opendrive.adoc
+    topicdir: topics
+    reusedir: reuse
+    imagesoutdir: ./images/generated_images
+    images_open_simulation_interface: 'interface:'
+    doc_open_simulation_interface: 'interface:'
+    doc_osi-sensor-model-packaging: 'sensor-model:'
+    page-repository-links: [["https://github.com/OpenSimulationInterface/open-simulation-interface", "Open Simulation Interface"],["https://github.com/OpenSimulationInterface/osi-sensor-model-packaging","OSI Sensor Model Packaging"],["https://github.com/OpenSimulationInterface/osi-validation","OSI Validation"]]
+
+  # END - Mandatory ASAM attributes
+  # doxygen_interface_version: "v3.2.0"  # The interface version that needs to be retrieved
+  # doxygen_document_date: "01.01.2000"  # The date associated with the document (optional)
+    doxygen_module: "gen"               # The module in which the output is stored
+    # doxygen_module_path: "gen"          # Path within module
+
+nav:
+- modules/specification/nav_introduction.adoc
+- modules/interface/nav.adoc
+- modules/sensor-model/nav.adoc
+- modules/specification/nav_contribution.adoc
+- modules/gen/doxynav.adoc
+- modules/specification/nav_loft.adoc
+# Add more items here as required.
+# Recommended: One navigation file per document/repository!
+# Recommended: Name your module (folder) as your document type, e.g. "standard" or "concept" or "topic-guidelines"
+# Format: - modules/<module-folder-name>/<navigation-file-name>.adoc

.antora/modules/specification/images

@@ -0,0 +1 @@
+../../../content/_static/images

.antora/modules/specification/nav_contribution.adoc

@@ -0,0 +1,76 @@
+* Contributing to ASAM OSI
+
+** xref:contributing/start_contributing.adoc[]
+
+** xref:contributing/reporting_issues.adoc[]
+
+** Contributing changes
+
+*** xref:contributing/licensing.adoc[]
+
+*** xref:contributing/dco.adoc[]
+
+*** xref:contributing/signing_off_commits.adoc[]
+
+*** xref:contributing/writing_commit_messages.adoc[]
+
+*** xref:contributing/contribution_rules.adoc[]
+
+*** xref:contributing/naming_conventions.adoc[]
+
+*** xref:contributing/branching_member.adoc[]
+
+*** xref:contributing/forking_no_member.adoc[]
+
+// *** xref:contributing/contributing_docs.adoc[]
+
+*** xref:contributing/commenting_messages.adoc[]
+
+*** xref:contributing/commenting_fields_enums.adoc[]
+
+*** xref:contributing/creating_references.adoc[]
+
+// *** xref:contributing/creating_images.adoc[]
+
+** Reviewing contributions
+
+*** xref:contributing/review_author.adoc[]
+
+*** xref:contributing/review_reviewer.adoc[]
+
+[glossary]
+* xref:general_docs/glossary.adoc[]
+
+
+[bibliography]
+* xref:general_docs/bibliography.adoc[]
+
+[appendix]
+* Release Notes
+
+:sectnums!:
+** xref:appendix/releases/v03.04.adoc[]
+:sectnums!:
+** xref:appendix/releases/v03.03.01.adoc[]
+:sectnums!:
+** xref:appendix/releases/v03.03.00.adoc[]
+:sectnums!:
+** xref:appendix/releases/v03.02.adoc[]
+:sectnums!:
+** xref:appendix/releases/v03.01.02.adoc[]
+:sectnums!:
+** xref:appendix/releases/v03.01.01.adoc[]
+:sectnums!:
+** xref:appendix/releases/v03.01.00.adoc[]
+:sectnums!:
+** xref:appendix/releases/v03.00.01.adoc[]
+:sectnums!:
+** xref:appendix/releases/v03.00.00.adoc[]
+:sectnums!:
+** xref:appendix/releases/v02.02.01.adoc[]
+:sectnums!:
+** xref:appendix/releases/v02.02.00.adoc[]
+:sectnums!:
+** xref:appendix/releases/v02.01.adoc[]
+:sectnums!:
+** xref:appendix/releases/v02.00.adoc[]

.antora/modules/specification/nav_introduction.adoc

@@ -0,0 +1,9 @@
+
+* Introduction
+** xref:general_docs/changes.adoc[]
+** xref:general_docs/deliverables.adoc[]
+** xref:general_docs/osi_repos.adoc[]
+** xref:general_docs/statements.adoc[]
+** xref:general_docs/conventions.adoc[]
+** xref:general_docs/versioning.adoc[]
+** xref:general_standard/relations_to_other_standards.adoc[]

.antora/modules/specification/pages

@@ -0,0 +1 @@
+../../../content

.github/workflows/antora-build.yml

@@ -0,0 +1,59 @@
+name: Antora Documentation Build
+
+on:
+  # create: # new branches or tags
+  # release: # new releases
+  push:
+    branches-ignore: [ main, master ]
+  # push: # on push. This may be removed later
+  # schedule: # periodic - needed because some of the content is from the other repos
+  #   - cron:  '30 5,20 * * *' # this is pretty often. Only needed during review phase
+
+jobs:
+  antora-build:
+    name: Build
+    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:
+    - name: Checkout generator
+      uses: actions/checkout@master
+      with:
+        repository: OpenSimulationInterface/osi-antora-generator
+        path: generator
+        submodules: true
+        fetch-depth: 0
+
+    - name: Modify site.yml
+      working-directory: generator
+      run: |
+        echo "$GITHUB_REF_NAME"
+        sed -i -E "s%(branches\:) \[antora\/base-antora-setup\] \# osi-documentation%\1 [$GITHUB_REF_NAME] \# osi-documentation%" site.yml
+        cat site.yml
+        sed -i -E "s/cd repo/cd generator/" run-build.sh
+        cat run-build.sh
+
+    - name: Generate site
+      uses: docker://ghcr.io/asam-ev/project-guide-docker:4
+      with:
+        entrypoint: sh
+        args: generator/run-build.sh
+
+    - name: Upload artifact
+      uses: actions/upload-artifact@v3
+      with: 
+        name: antora-build
+        path: ./generator/site
+
+

.github/workflows/asciidoc-build.yml

@@ -28,15 +28,15 @@ jobs:
       uses: actions/checkout@v2
       with:
         repository: OpenSimulationInterface/open-simulation-interface
-        path: open-simulation-interface
+        path: content/open-simulation-interface
         fetch-depth: 0
 
 
     - name: Checkout OSI Sensor Model Packaging
       uses: actions/checkout@v2
       with:
         repository: OpenSimulationInterface/osi-sensor-model-packaging
-        path: osi-sensor-model-packaging
+        path: content/osi-sensor-model-packaging
 
     - name: Checkout proto2cpp
       uses: actions/checkout@v2
@@ -47,24 +47,24 @@ jobs:
     # Versioning
     - name: Get versioning
       id: get_version
-      working-directory: open-simulation-interface
+      working-directory: content/open-simulation-interface
       run: echo ::set-output name=VERSION::$(git describe --always)
 
     # replaces the placeholder for versioning in the main mapping file
     - name: Apply versioning to Adoc
       run: |
-        grep ":revnumber:" index.adoc
-        sed -i -e "s/--localbuild--/master (${{ steps.get_version.outputs.VERSION }})/" index.adoc
-        grep ":revnumber:" index.adoc
+        grep ":revnumber:" content/_config.adoc
+        sed -i -e "s/--localbuild--/main (${{ steps.get_version.outputs.VERSION }})/" content/_config.adoc
+        grep ":revnumber:" content/_config.adoc
 
     - name: Remove docdate for online hosted document
-      run: sed 's/^:revdate:.*/:!revdate:/' index.adoc
+      run: sed 's/^:revdate:.*/:!revdate:/' content/_config.adoc
 
     # run Asciidoctor
     - name: Build HTML
       uses: avattathil/asciidoctor-action@master
       with:
-        program: "asciidoctor -D . --failure-level WARN -r asciidoctor-diagram -r asciidoctor-bibtex -a mathjax --trace --backend=html5 index.adoc -o open-simulation-interface_V${{ steps.get_version.outputs.VERSION }}.html"
+        program: "asciidoctor -D . --failure-level WARN -r asciidoctor-diagram -r asciidoctor-bibtex -a mathjax --trace --backend=html5 content/index.adoc -o open-simulation-interface_V${{ steps.get_version.outputs.VERSION }}.html"
 
     # Upload artifact.
     - name: Upload HTML Artifact

README.adoc

@@ -1,27 +1,39 @@
 = OSI Documentation
 
-This repo hosts the asciidoc-based part of the documentation. 
-It contains generals parts of the content and a CI-pipeline that renders the document and deploys it the the https://opensimulationinterface.github.io/osi-documentation/[gh-pages of this repo].
+This repo hosts the AsciiDoc-based part of the documentation. 
+It contains generals parts of the content and a CI-pipeline that renders the document with Asciidoctor and deploys it to the https://opensimulationinterface.github.io/osi-documentation/[gh-pages of this repo].
+
+// TODO: Update if Asciidoctor is completely dropped!
 
 == ASAM OSI (R) official documentation
 
 See the documentation https://opensimulationinterface.github.io/osi-documentation/[here].
 
 
-== Build Pipeline
-
+== Build pipeline 
+=== Asciidoctor pipeline
 
 image::https://github.com/OpenSimulationInterface/osi-documentation/actions/workflows/asciidoc-build.yml/badge.svg[link=https://github.com/OpenSimulationInterface/osi-documentation/actions/workflows/asciidoc-build.yml]
 
+The pipeline collects the documentation from both https://github.com/OpenSimulationInterface/open-simulation-interface[open-simulation-interface] and https://github.com/OpenSimulationInterface/osi-sensor-model-packaging[osi-sensor-model-packaging] and integrates it into skeleton of this repo. 
+As with all ASAM Asciidoctor projects, the complete document structure is described in the mapping file https://github.com/OpenSimulationInterface/osi-documentation/blob/master/index.adoc[index.adoc].
+
+=== Antora pipeline 
+image::https://github.com/OpenSimulationInterface/osi-antora-generator/actions/workflows/site-build.yml/badge.svg?branch=main[link=https://github.com/OpenSimulationInterface/osi-antora-generator/actions/workflows/site-build.yml]
 
-The pipeline collects the documentation from both https://github.com/OpenSimulationInterface/open-simulation-interface[open-simulation-interface] and https://github.com/OpenSimulationInterface/osi-sensor-model-packaging[osi-sensor-model-packaging] and integrates it into skeleton of this repo. As with all ASAM asciidoc project the complete document structure is described in the mapping file https://github.com/OpenSimulationInterface/osi-documentation/blob/master/index.adoc[index.adoc].
+NOTE: This pipeline runs on https://github.com/OpenSimulationInterface/osi-antora-generator.
 
 
 == How To build and change documentation locally
 
-The following instruction shows how to build the document locally. Take note that the document is build with a version 'localbuild' in the document and filename.
+IMPORTANT: These instructions relate ONLY to the Asciidoctor build. 
+For Antora, check the https://github.com/OpenSimulationInterface/osi-antora-generator[ASAM OSI Antora generator].
+
+
+The following instructions show how to build the document locally. 
+Take note that the document is built with a version 'localbuild' in the document and filename.
 
-The instruction should work on Windows, Linux and MacOS.
+The instruction should work on Windows, Linux, and MacOS.
 
 . *Precondition*: have docker and docker-compose installed.
 +

content/_config.adoc

@@ -0,0 +1,56 @@
+
+// This file contains AsciiDoc attributes that shall be used in every AsciiDoc file.
+// NOTE: Its content is only applied for Asciidoctor!
+// If the same attribute is defined in the antora.yml (without @), the antora.yml definition takes precedence for Antora.
+
+ifndef::root-path[:root-path: ./]
+
+:asciidoc-resources: {root-path}../asciidoc-resources
+// :asciidoc-resources: ../asciidoc-resources
+:appendix-caption: Annex
+
+// ifndef::use-antora-rules,include-only-once[]
+ifndef::include-only-once[]
+:GLO_VAR_STA_ASAM_OpenCRG: ASAM OpenCRG
+:glo_var_sta_asam_opencrg: {GLO_VAR_STA_ASAM_OpenCRG}
+:GLO_VAR_STA_ASAM_OpenDRIVE: ASAM OpenDRIVE
+:GLO_VAR_STA_ASAM_OpenLABEL: ASAM OpenLABEL
+:GLO_VAR_STA_ASAM_OpenODD: ASAM OpenODD
+:GLO_VAR_STA_ASAM_OSI: ASAM OSI®
+:GLO_VAR_STA_ASAM_OpenSCENARIO: ASAM OpenSCENARIO
+:GLO_VAR_STA_ASAM_OpenXOntology: ASAM OpenXOntology
+:GLO_VAR_STA_BSI_PAS_1883: BSI PAS 1883
+:revnumber: --localbuild--
+:revdate: {docdate}
+:bibtex-file: ./content/general_docs/bibliography.bib
+// Replace PLACEHOLDER with the name of your standard, e.g. OpenDRIVE
+:THIS_STANDARD: {GLO_VAR_STA_ASAM_OSI}
+:THIS_STANDARD_TITLE: {GLO_VAR_STA_ASAM_OSI}
+:asam-terminology: https://code.asam.net/common/asam-terminology/-/raw/main/terms_and_definitions_opendrive.adoc
+:imagesdir: {root-path}_static/images
+:include-only-once: true
+:topicdir: topics
+:reusedir: reuse
+:toclevels: 3
+:xrefstyle: full
+// :images_osi-sensor-model-packaging: ../../osi-sensor-model-packaging/doc/images
+:doc_open_simulation_interface: open-simulation-interface/doc/
+:doc_osi-sensor-model-packaging: osi-sensor-model-packaging/doc/
+:images_open_simulation_interface: ../../open-simulation-interface/doc/images
+// Since a document spanning multiple repos is rendered here, the pathing regarding images is a bit involved.
+// We create a variable for every repo that is included. It point to the repo in question.
+// If the subrepo is rendered seperatly, then the variable is set to just "./images" with ifdef.
+// Please note that this variable has to used in all image includes. Includes here have to use "image::./images..."
+// :images_osi_sensor_model_packaging: ./osi-sensor-model-packaging/doc/images  // example
+:imagesoutdir: ./images/generated_images
+:page-feedbackurl: https://github.com/OpenSimulationInterface/osi-documentation/issues/new
+
+endif::[]
+
+ifndef::use-antora-rules[]
+include::{asciidoc-resources}/preamble.adoc[]
+endif::[]
+
+ifdef::env-gitlab[]
+:relfilesuffix: .adoc
+endif::[]

appendix/releases/compatibility.adoc → content/appendix/releases/compatibility.adoc

@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../../
+include::{root-path}_config.adoc[]
+endif::[]
 = Compatibility
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

appendix/releases/v02.00.adoc → content/appendix/releases/v02.00.adoc

@@ -1,7 +1,14 @@
-
-
+ifndef::include-only-once[]
+:root-path: ../../
+include::{root-path}_config.adoc[]
+endif::[]
+ifdef::use-antora-rules[]
+:reftext: v2.0.0 - OSI Initial Commit
+= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.0.0[{reftext}]
+endif::[]
+ifndef::use-antora-rules[]
 = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.0.0[v2.0.0 - OSI Initial Commit]
-
+endif::[]
 
 This is the initial version of the Open Simulation Interface (OSI).