Merge pull request #22 from asam-ev/antora-configuration

Antora configuration setup

.antora/modules/specification/pages/_config.adoc

@@ -0,0 +1,37 @@
+
+// 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: ./]
+
+:partials-path: {root-path}../_additional_content
+: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_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/bibliography.bib
+// Replace PLACEHOLDER with the name of your standard, e.g. OpenDRIVE
+:THIS_STANDARD: ASAM OpenMATERIAL
+:imagesdir: {root-path}/_images
+:include-only-once: true
+endif::[]
+
+ifndef::use-antora-rules[]
+include::{asciidoc-resources}/preamble.adoc[]
+endif::[]
+
+ifdef::env-gitlab[]
+:relfilesuffix: .adoc
+endif::[]

.antora/modules/specification/pages/bibliography.adoc

@@ -0,0 +1,3 @@
+= Bibliography
+[bibliography]
+bibliography::[]

.antora/modules/specification/pages/bibliography.bib

@@ -0,0 +1,47 @@
+% Encoding: UTF-8
+
+@Standard{ocr,
+    title  = {https://www.asam.net/index.php?eID=dumpFile&t=f&f=3950&token=21a7ae456ec0eb0f9ec3aee5bae3e8c9ebaea140[__ASAM OpenCRG__^], __1.2.0__}
+}
+
+@Standard{osc,
+    title  = {https://www.asam.net/index.php?eID=dumpFile&t=f&f=4908&token=ae9d9b44ab9257e817072a653b5d5e98ee0babf8[__ASAM OpenSCENARIO^], __1.2.0__}
+}
+
+@Standard{iso3166-1,
+    title  = {https://www.iso.org/standard/72482.html[__ISO 3166-1:2020__^], Codes for the representation of names of countries and their subdivisions, Part 1: Country code}
+}
+
+@Standard{iso3166-2,
+    title  = {https://www.iso.org/standard/72483.html[__ISO 3166-2:2020__^], Codes for the representation of names of countries and their subdivisions, Part 2: Country subdivision code}
+}
+
+@Standard{iso8601,
+    title  = {https://www.iso.org/iso-8601-date-and-time-format.html[__ISO 8601:2019__^], Date and time format}
+}
+
+@Standard{iso8855,
+    title  = {https://www.iso.org/standard/51180.html[__ISO 8855:2011__^], Road vehicles — Vehicle dynamics and road-holding ability, Vocabulary}
+}
+
+@Standard{iso19111,
+    title  = {https://www.iso.org/standard/74039.html[__ISO 19111:2019__^], Geographic information, Referencing by coordinates}
+}
+
+@Standard{omguml,
+    title  = {__OMG®️__, https://www.omg.org/spec/UML/2.5.1/About-UML[__Unified Modeling Language®️ (OMG UML®️)__^], __2.5.1__}
+}
+
+@Standard{w3cxml,
+    title  = {__W3C__, https://www.w3.org/TR/2008/REC-xml-20081126[__Extensible Markup Language (XML)__^], __1.0 (Fifth Edition)__}
+}
+
+@Standard{w3cxmlschema,
+    title  = {__W3C__, https://www.w3.org/TR/xmlschema-1[__XML Schema Part 1__^], __Structures Second Edition__}
+}
+
+@misc{EPSG,
+    author = {EPSG.io},
+    title  = {https://epsg.io[Coordinate Systems Worldwide^]},
+    note   = {[viewed 2024-03-18]}
+}

.antora/modules/specification/pages/general_docs/abbreviations.adoc

@@ -0,0 +1,21 @@
+[#top-abbreviations-abbreviations]
+= Abbreviations
+
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
+
+ASAM::
+Association for Standardization of Automation and Measuring Systems
+
+ECU::
+Electronic Control Unit
+
+UML::
+Unified Modeling Language
+
+XML::
+Extensible Markup Language
+
+> Update as needed

.antora/modules/specification/pages/general_docs/backward_compatibility.adoc

@@ -0,0 +1,11 @@
+[#top-backward_compatibility-backward_compatibility]
+= Backward compatibility
+
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
+
+{THIS_STANDARD} is backwards compatible with {THIS_STANDARD}
+
+

.antora/modules/specification/pages/general_docs/foreword.adoc

@@ -0,0 +1,17 @@
+[#top-preface-foreword]
+= Foreword
+
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
+
+ASAM e.V. (Association for Standardization of Automation and Measuring Systems) is a non-profit organization that promotes standardization of tool chains in automotive development and testing.
+Our members are international car manufacturers, suppliers, tool vendors, engineering service providers, and research institutes.
+ASAM standards are developed by experts from our member companies and are based on real use cases.
+ASAM is the legal owner of these standards and is responsible for their distribution and marketing.
+
+ASAM standards span a wide range of use cases in automotive development, test, and validation.
+They define file formats, data models, protocols, and interfaces.
+The standards enable easy exchange of data and tools within and across tool chains.
+They are applied worldwide.

.antora/modules/specification/pages/general_docs/introduction.adoc

@@ -0,0 +1,79 @@
+[#top-preface-introduction]
+= Introduction
+
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
+
+== Overview
+Overview of {THIS_STANDARD}.
+
+== Conventions and notations
+
+[#sec-modal-verbs]
+=== Modal verbs
+
+To ensure compliance with the {THIS_STANDARD} specification, users need to be able to distinguish between requirements, recommendations, permissions, possibilities and capabilities, and external constraints.
+
+The following rules for using modal verbs apply:
+
+[#tab-modal-verbs]
+.Verbal forms for expressions of provisions
+[%header, cols="20, 15, 65"]
+|===
+|Provision                  |Verbal form        |Definition
+|Requirement                |shall, shall not   |A requirement conveys objectively verifiable criteria to be fulfilled and from which no deviation is permitted if conformance with the document is to be claimed.
+|Recommendation             |should, should not |A recommendation conveys a suggested possible choice or course of action deemed to be particularly suitable without necessarily mentioning or excluding others.
+|Permission                 |may                |A permission conveys consent or liberty (or opportunity) to do something.
+|Possibility and capability |can, cannot        |A possibility conveys expected or conceivable material, physical or causal outcome. +
+                                                 A capability conveys the ability, fitness, or quality necessary to do or achieve a specified thing.
+|External constraint        |must               |An external constraint or obligation on the user of the document, for example laws of nature or particular conditions existing in some countries or regions, that is not stated as a provision of the document.
+                                                 External constraints are not requirements of the document.
+                                                 They are given for the information of the user.
+|===
+
+[#sec-normative-and-informative-content]
+=== Normative and informative content
+
+Content in this specification can be normative or informative.
+The sections listed in <<tab-normative-informative-content>> are normative or informative per definition.
+Further informative content is shown in table <<tab-informative-text-components>>.
+
+[#tab-normative-informative-content]
+.Normative and informative sections
+[%header, cols=2*]
+|===
+|Section                                      |Indication
+|Foreword                                     |Informative
+|Introduction                                 |Informative
+|Scope                                        |Normative
+|Normative references                         |Informative
+|Terms and definitions                        |Normative
+|Abbreviations                                |Normative
+|Backward compatibility                       |Normative
+|First to last specification-specific section |Normative
+|Annexes                                      |Annexes can be normative or informative. The annex heading contains the indication "(normative)" or "(informative)".
+|Bibliography                                 |Informative
+|===
+
+All other sections in this specification are normative.
+
+[#tab-informative-text-components]
+.Informative text components
+[%header, cols="30, 70"]
+|===
+|Text components   |Hints
+|Notes             |The document shall be usable without notes.
+|Footnotes         |The document shall be usable without footnotes.
+|Examples          |The document shall be usable without examples.
+|Sequence diagrams |The document shall be usable without sequence diagrams.
+|===
+
+Notes, footnotes, and examples shall not contain requirements or any information considered indispensable for the use of the document, for example, instructions or permission.
+
+== Deliverables
+
+The following deliverables are provided for {THIS_STANDARD}:
+
+> Define the deliverables of this project here

.antora/modules/specification/pages/general_docs/normative_references.adoc

@@ -0,0 +1,25 @@
+[#top-normative_references-normative_references]
+= Normative references
+
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
+
+The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document.
+For dated references, only the edition cited applies.
+For undated references, the latest edition of the referenced document (including any amendments) applies.
+
+Standards referenced in this section are normative in such a way that parts or the whole standard shall be applied when implementing the referenced functionality.
+Standards referenced in this section shall be cited normatively in the text.
+
+* {GLO_VAR_STA_ASAM_OpenCRG} cite:[ocr]
+* ASAM OpenSCENARIO cite:[osc]
+* ISO 3166-1 cite:[iso3166-1]
+* ISO 3166-2 cite:[iso3166-2]
+* ISO 8855 cite:[iso8855]
+* ISO 8601 cite:[iso8601]
+* ISO 19111 cite:[iso19111]
+* OMG® UML 2.5.1 cite:[omguml]
+* W3C XML cite:[w3cxml]
+* W3C XML Schema cite:[w3cxmlschema]

.antora/modules/specification/pages/general_docs/scope.adoc

@@ -0,0 +1,11 @@
+[#top-scope-scope]
+= Scope
+
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
+
+{THIS_STANDARD} specifies ...
+
+> Define the scope of this document/standard

.antora/modules/specification/pages/index.adoc

@@ -0,0 +1,60 @@
+[#top-this-standard]
+:root-path: ./
+include::{root-path}_config.adoc[]
+//NOTE: All central attributes for Asciidoctor have to be defined in the _config.adoc AND in the antora.yml in the .antora folder in root
+= ASAM OpenMATERIAL
+// DO NOT USE THE ATTRIBUTE {THIS_STANDARD} in the document title, it will break with Antora build pipeline!
+
+// DO NOT CHANGE!!!
+//
+:titleoffset!:
+:sectnums!:
+
+
+[IMPORTANT]
+.Disclaimer
+====
+This document is the copyrighted property of ASAM e.V.
+In alteration to the regular https://www.asam.net/license[license terms], ASAM allows unrestricted distribution of this standard. §2 (1) of ASAM's regular https://www.asam.net/license[license terms] is therefore substituted by the following clause: "The licensor grants everyone a basic, non-exclusive and unlimited license to use the standard {THIS_STANDARD}".
+====
+//
+// DO NOT CHANGE!!!
+
+
+:antora_mapping: true
+ifndef::use-antora-rules[]
+
+[preface]
+include::general_docs/foreword.adoc[leveloffset=+1]
+[preface]
+include::general_docs/introduction.adoc[leveloffset=+1]
+
+:sectnums:
+include::general_docs/scope.adoc[leveloffset=+1]
+
+include::general_docs/normative_references.adoc[leveloffset=+1]
+
+include::terms_and_definitions/terms_and_definitions.adoc[leveloffset=+1]
+
+include::general_docs/abbreviations.adoc[leveloffset=+1]
+
+include::general_docs/backward_compatibility.adoc[leveloffset=+1]
+
+// Add further sections and chapters here as needed
+
+: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]
+endif::[]
+:!antora_mapping:

.antora/modules/specification/pages/loft/list_of_figures.adoc

@@ -0,0 +1,2 @@
+// AUTOMATICALLY GENERATED -- DO NOT CHANGE
+= List of figures

.antora/modules/specification/pages/loft/list_of_tables.adoc

@@ -0,0 +1,2 @@
+// AUTOMATICALLY GENERATED -- DO NOT CHANGE
+= List of tables

.antora/modules/specification/pages/terms_and_definitions/terms_and_definitions.adoc

@@ -0,0 +1,12 @@
+[#top-terms_and_definitions-terms_and_definitions]
+= Terms and definitions
+
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
+
+TODO: Add terms and definitions
+
+Static road network::
+Collection of connected roads enriched by static objects that do not change during runtime of a simulation.

.github/workflows/antora-build.yml

@@ -0,0 +1,27 @@
+name: Antora Documentation Build
+# Based on https://github.com/OpenSimulationInterface/osi-documentation/blob/master/.github/workflows/antora-build.yml
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  trigger_antora:
+    name: Trigger antora generator
+
+    runs-on: Ubuntu-latest
+
+    env:
+      MUP_KEY: ${{ secrets.MACHINE_USER_PAT }}
+
+    steps:
+    - name: Trigger generator
+      if: ${{ env.MUP_KEY != '' }}
+      uses: peter-evans/repository-dispatch@v3
+      with:
+        token: ${{ secrets.MACHINE_USER_PAT }}
+        event-type: antora-build-trigger
+        repository:  # Add fork of https://code.asam.net/common/templates/antora-base-repo-example
+        client-payload: '{"src": "${{ github.repository }}", "ref": "${{ github.ref }}", "sha": "${{ github.sha }}", "head_ref": "${{ github.head_ref }}"}'
+