Merge pull request #666 from OpenSimulationInterface/antora/base-anto…

…ra-setup Build: Create base Antora setup
OpenSimulationInterface · Oct 11, 2022 · 562cbb1 · 562cbb1
2 parents 700133d + c3ca3c9
commit 562cbb1
Show file tree

Hide file tree

Showing 49 changed files with 290 additions and 22 deletions.
diff --git a/.antora/antora.yml b/.antora/antora.yml
@@ -0,0 +1,10 @@
+# Component name (without spaces!). All content repositories with the same component name are merged in Antora.
+name: asamosi
+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'
diff --git a/.antora/modules/gen/doxynav.adoc b/.antora/modules/gen/doxynav.adoc
diff --git a/.antora/modules/interface/images b/.antora/modules/interface/images
@@ -0,0 +1 @@
+../../../doc/images
diff --git a/.antora/modules/interface/nav.adoc b/.antora/modules/interface/nav.adoc
@@ -0,0 +1,22 @@
+[preface]
+* xref:00_preface/00_foreword.adoc[]
+[preface]
+* xref:00_preface/01_introduction.adoc[]
+* xref:01_scope/01_scope.adoc[]
+* xref:02_normative_references/01_normative_references.adoc[]
+* xref:03_terms_and_definitions/01_terms_and_definitions.adoc[]
+* xref:04_abbreviations/01_abbreviations.adoc[]
+* xref:05_backward_compatibility/01_backward_compatibility.adoc[]
+
+[appendix]
+* xref:xx_annexes/REPLACE_ME.adoc[]
+[bibliography]
+* xref:bibliography.adoc[]
+
+:sectnums!:
+* xref:list_of_figures.adoc[]
+
+:sectnums!:
+* xref:list_of_tables.adoc[]
+
+// TODO Replace with generator
diff --git a/.antora/modules/interface/pages b/.antora/modules/interface/pages
@@ -0,0 +1 @@
+../../../doc
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -11,8 +11,8 @@ Is this a bug fix or a feature? Does it break any existing functionality or forc
 How has it been tested?
 
 #### Take this checklist as orientation for yourself, if this PR is ready for the Change Control Board:
-- [ ] My suggestion follows the [style and contributors guidelines](https://opensimulationinterface.github.io/osi-documentation/open-simulation-interface/doc/howtocontribute.html).
-- [ ] I have taken care about the [documentation](https://opensimulationinterface.github.io/osi-documentation/open-simulation-interface/doc/commenting.html).
+- [ ] My suggestion follows the [style and contributors guidelines](https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/specification/contributing/start_contributing.html).
+- [ ] I have taken care about the [message documentation](https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/specification/contributing/commenting_messages.html) and the [fields and enums documentation](https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/specification/contributing/commenting_fields_enums.html).
 - [ ] I have done the [DCO signoff](https://opensimulationinterface.github.io/osi-documentation/open-simulation-interface/doc/howtocontribute.html#developer-certification-of-origin-dco).
 - [ ] My changes generate no errors when passing CI tests. 
 - [ ] I have successfully implemented and tested my fix/feature locally.

diff --git a/README.md b/README.md
@@ -9,6 +9,8 @@ As the complexity of automated driving functions rapidly increases, the requirem
 
 For more information on OSI see the [official documentation](https://opensimulationinterface.github.io/osi-documentation/) or the [official reference documentation](https://opensimulationinterface.github.io/open-simulation-interface/) for defined protobuf messages.
 
+<!-- TODO: Update with new Antora hosting -->
+
 [1] Hanke, T., Hirsenkorn, N., van-Driesten, C., Garcia-Ramos, P., Schiementz, M., Schneider, S. & Biebl, E. (2017, February 03). *A generic interface for the environment perception of automated driving functions in virtual scenarios.* Retrieved January 25, 2020, from https://www.hot.ei.tum.de/forschung/automotive-veroeffentlichungen/
 
 ## Usage

diff --git a/doc/_config.adoc b/doc/_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: ./]
+
+:partials-path: {root-path}../_additional_content
+:asciidoc-resources: ../asciidoc-resources
+:appendix-caption: Annex
+:page-feedbackurl: https://github.com/OpenSimulationInterface/open-simulation-interface/issues/new
+
+// 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}
+:asam-terminology: https://code.asam.net/common/asam-terminology/-/raw/main/terms_and_definitions_opendrive.adoc
+:imagesdir: {root-path}/images
+:include-only-once: true
+:topicdir: topics
+:reusedir: reuse
+:toclevels: 3
+:xrefstyle: full
+:images_open_simulation_interface: {imagesdir}
+// :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/
+// 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
+
+endif::[]
+
+ifndef::use-antora-rules[]
+include::{asciidoc-resources}/preamble.adoc[]
+endif::[]
+
+ifdef::env-gitlab[]
+:relfilesuffix: .adoc
+endif::[]
+
diff --git a/doc/architecture/architecture_overview.adoc b/doc/architecture/architecture_overview.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Overview of OSI architecture
 
 OSI contains an object-based environment description that uses the message format of the https://github.com/protocolbuffers/protobuf/wiki[Protocol Buffer] library.
@@ -7,6 +11,7 @@ Top-level messages define the `GroundTruth` interface, the `SensorData` interfac
 
 The following figure shows the interfaces and models involved in modeling a sensor.
 
+[#fig-open-simulation-interface-overview]
 .Open Simulation Interface overview
 image::{images_open_simulation_interface}/osi-context.png[1100]
 
@@ -16,12 +21,14 @@ The `TrafficCommand` interface makes it possible to send commands to traffic par
 The `TrafficUpdate` interface makes it possible to receive the updated state from traffic participant models.
 The following figure shows the interfaces of a generic traffic participant.
 
+[#fig-interface-traffic-participant]
 .Interface of a traffic participant
 image::{images_open_simulation_interface}/osi-traffic-participant-principle.png[1100]
 
 Traffic participant models may use other OSI interfaces internally, for example, to model autonomous vehicles.
 The following figure shows a more advanced use case for traffic participants.
 
+[#fig-traffic-participant-sensor-models]
 .Traffic participant with sensor models, AD function, and dynamic model
 image::{images_open_simulation_interface}/osi-traffic-participant-advanced.png[1100]
 

diff --git a/doc/architecture/data_layer.adoc b/doc/architecture/data_layer.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Data layer
 
 The OSI data layer is defined in the message specifications using the ProtoBuf IDL cite:[protobuf].

diff --git a/doc/architecture/environmental_effect_model.adoc b/doc/architecture/environmental_effect_model.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Environmental effect model
 
 Environmental effect models consume `SensorView` messages and produce `SensorView` messages.

diff --git a/doc/architecture/feature_data.adoc b/doc/architecture/feature_data.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Feature data
 
 `FeatureData` messages contain detected features in the reference frame of a sensor.

diff --git a/doc/architecture/formatting_scripts.adoc b/doc/architecture/formatting_scripts.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Trace-file formatting scripts
 
 The OSI repository contains Python scripts for converting trace files from one format to another.
@@ -49,4 +53,4 @@ The default value is `None`.
 
 **Related topics**
 
-* <<_osi_trace_file_formats>>
+* <<top-osi_trace_file_formats>>
diff --git a/doc/architecture/ground_truth.adoc b/doc/architecture/ground_truth.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Ground truth
 
 `GroundTruth` messages describe the simulated environment containing all simulated objects in the global coordinate system at consecutive time instances.

diff --git a/doc/architecture/logical_model.adoc b/doc/architecture/logical_model.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Logical model
 
 Logical models consume `SensorData` messages and produce `SensorData` messages.

diff --git a/doc/architecture/packaging_layer.adoc b/doc/architecture/packaging_layer.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Packaging layer
 
 The OSI packaging layer specifies how components that use the OSI data layer, for example, sensor models, are packaged for exchange.

diff --git a/doc/architecture/proto-files.adoc b/doc/architecture/proto-files.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Protobuffer files
 
 TODO: Add general description.

diff --git a/doc/architecture/reference_points_coordinate_systems.adoc b/doc/architecture/reference_points_coordinate_systems.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Coordinate systems, reference points and coordinate transformation
 
 OSI uses DIN ISO 8855:2013-11 cite:[iso8855] for coordinate systems and transformations between coordinate systems.

diff --git a/doc/architecture/sensor_data.adoc b/doc/architecture/sensor_data.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Sensor data
 
 `SensorData` messages imitate the output of real sensors.

diff --git a/doc/architecture/sensor_model.adoc b/doc/architecture/sensor_model.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Sensor model
 
 Sensor models consume `SensorView` messages and produce `SensorData` messages.

diff --git a/doc/architecture/sensor_view.adoc b/doc/architecture/sensor_view.adoc
@@ -1,9 +1,13 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Sensor view
 
 The sensor view provides the input to OSI sensor models.
 `SensorView` messages are derived from `GroundTruth` messages.
 All information regarding the environment is given with respect to the virtual sensor coordinate system, with two exceptions:
 
 * Physical technology-specific data, given with respect to the physical sensor coordinate system specified in the corresponding physical sensor's mounting position.
-  One example of technology-specific data is: https://opensimulationinterface.github.io/open-simulation-interface/structosi3_1_1CameraSensorView.html#ac58456a34babf78792ea2608eb963f36[`image_data` of `osi3::CameraSensorView`]
+  One example of technology-specific data is: xref:gen:structosi3_1_1CameraSensorView.adoc#ac58456a34babf78792ea2608eb963f36[`image_data` of `osi3::CameraSensorView`]
 * Ground truth given in the global coordinate system.
diff --git a/doc/architecture/sensor_view_configuration.adoc b/doc/architecture/sensor_view_configuration.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Sensor-view configuration
 
 The sensor view is flexibly defined to provide different kinds of sensor models with an appropriate input.

diff --git a/doc/architecture/test_scripts.adoc b/doc/architecture/test_scripts.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Test scripts
 
 TODO: Add general description.

diff --git a/doc/architecture/trace_file_formats.adoc b/doc/architecture/trace_file_formats.adoc
@@ -1,3 +1,8 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
+[#top-osi_trace_file_formats]
 = OSI trace file formats
 
 There are multiple formats for storing multiple serialized OSI messages in one trace file.

diff --git a/doc/architecture/trace_file_naming.adoc b/doc/architecture/trace_file_naming.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = OSI trace file naming conventions
 
 **Name format**
@@ -30,6 +34,8 @@ Trace file contains `TrafficCommand` messages.
 
 Given an OSI trace file with the following information:
 
+[#tab-example-osi-trace-file-information]
+.Example OSI trace file information
 [cols="1,1"]
 |===
 |Timestamp (ISO 8601) cite:[iso8601]

diff --git a/doc/architecture/traffic_command.adoc b/doc/architecture/traffic_command.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Traffic command
 
 `TrafficCommand` messages contain control commands from the scenario engine to traffic participant models.
diff --git a/doc/architecture/traffic_participant.adoc b/doc/architecture/traffic_participant.adoc
@@ -1,9 +1,13 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Traffic participant
 
 A traffic participant is an element of the simulated world and can change its state during simulation time, for example, its position and orientation.
 A traffic participant represents one of the following:
 
-- Living being.
+- Living being
 - Means of transportation for living beings
 - Means of transportation for goods
 - Any other movable object that may travel on the road network
@@ -14,12 +18,14 @@ The ego vehicle is therefore also a traffic participant.
 
 The following figure shows the interface of a traffic participant.
 
+[#fig-interface-traffic-participant-2]
 .Interface of a traffic participant
 image::{images_open_simulation_interface}/osi-traffic-participant-principle.png[1100]
 
 Traffic participant models may use other OSI interfaces internally, for example, to model autonomous vehicles.
 The following figure shows a more advanced use case for traffic participants.
 
+[#fig-traffic-participant-other-osi-interfaces]
 .Traffic participant using other OSI interfaces internally
 image::{images_open_simulation_interface}/osi-traffic-participant-advanced.png[1100]
 

diff --git a/doc/architecture/traffic_update.adoc b/doc/architecture/traffic_update.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Traffic update
 
 `TrafficUpdate` messages are provided by traffic participants.

diff --git a/doc/architecture/vehicle_dynamics.adoc b/doc/architecture/vehicle_dynamics.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Vehicle dynamics
 
 TODO: Content to be added in future release.
diff --git a/doc/misc/osi_vision.adoc b/doc/misc/osi_vision.adoc
@@ -1,3 +1,7 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
 = Idea behind Open Simulation Interface
 
 {THIS_STANDARD} Open Simulation Interface is a specification for interfaces between models and components of a distributed simulation.

diff --git a/doc/open-simulation-interface_user_guide.adoc b/doc/open-simulation-interface_user_guide.adoc
@@ -1,22 +1,9 @@
-ifndef::THIS_STANDARD[]
-
-:asciidoc-resources: ../asciidoc-resources
-include::{asciidoc-resources}/preamble.adoc[]
-
-:revnumber: --localbuild--
-:revdate: {docdate}
-
-:topicdir: topics
-:reusedir: reuse
-
-:imagesdir: .
-:images_open_simulation_interface: ./images
-
-
-endif::[]
-
+:root-path: ./
+include::{root-path}_config.adoc[]
 = Open Simulation Interface
 
+:antora_mapping: title;numbered
+ifndef::use-antora-rules[]
 
 include::./misc/osi_vision.adoc[leveloffset=+1]
 
@@ -115,3 +102,6 @@ include::./setup/installing_windows_python.adoc[leveloffset=+2]
 //== Improving performance
 
 //TODO: Define topics and issues regarding performance.
+
+endif::[]
+:!antora-mapping: