diff --git a/.antora/antora.yml b/.antora/antora.yml new file mode 100644 index 00000000..557aec61 --- /dev/null +++ b/.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- (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® # 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//.adoc \ No newline at end of file diff --git a/.antora/modules/specification/images b/.antora/modules/specification/images new file mode 120000 index 00000000..e4084286 --- /dev/null +++ b/.antora/modules/specification/images @@ -0,0 +1 @@ +../../../content/_static/images \ No newline at end of file diff --git a/.antora/modules/specification/nav_contribution.adoc b/.antora/modules/specification/nav_contribution.adoc new file mode 100644 index 00000000..887e2def --- /dev/null +++ b/.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[] diff --git a/.antora/modules/specification/nav_introduction.adoc b/.antora/modules/specification/nav_introduction.adoc new file mode 100644 index 00000000..93ae8db2 --- /dev/null +++ b/.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[] diff --git a/.antora/modules/specification/nav_loft.adoc b/.antora/modules/specification/nav_loft.adoc new file mode 100644 index 00000000..e69de29b diff --git a/.antora/modules/specification/pages b/.antora/modules/specification/pages new file mode 120000 index 00000000..f0bfb077 --- /dev/null +++ b/.antora/modules/specification/pages @@ -0,0 +1 @@ +../../../content \ No newline at end of file diff --git a/.github/workflows/antora-build.yml b/.github/workflows/antora-build.yml new file mode 100644 index 00000000..80ad1858 --- /dev/null +++ b/.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 + + \ No newline at end of file diff --git a/.github/workflows/asciidoc-build.yml b/.github/workflows/asciidoc-build.yml index 4e44ea48..252434ff 100644 --- a/.github/workflows/asciidoc-build.yml +++ b/.github/workflows/asciidoc-build.yml @@ -28,7 +28,7 @@ jobs: uses: actions/checkout@v2 with: repository: OpenSimulationInterface/open-simulation-interface - path: open-simulation-interface + path: content/open-simulation-interface fetch-depth: 0 @@ -36,7 +36,7 @@ jobs: 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 diff --git a/README.adoc b/README.adoc index 958ac5b5..79050af6 100644 --- a/README.adoc +++ b/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. + diff --git a/content/_config.adoc b/content/_config.adoc new file mode 100644 index 00000000..b645865b --- /dev/null +++ b/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::[] diff --git a/_static/images/osi-context.png b/content/_static/images/osi-context.png similarity index 100% rename from _static/images/osi-context.png rename to content/_static/images/osi-context.png diff --git a/_static/images/osi-traffic-participant-advanced.png b/content/_static/images/osi-traffic-participant-advanced.png similarity index 100% rename from _static/images/osi-traffic-participant-advanced.png rename to content/_static/images/osi-traffic-participant-advanced.png diff --git a/_static/images/osi-traffic-participant-principle.png b/content/_static/images/osi-traffic-participant-principle.png similarity index 100% rename from _static/images/osi-traffic-participant-principle.png rename to content/_static/images/osi-traffic-participant-principle.png diff --git a/_static/images/osi-traffic-participant-use-case-1.png b/content/_static/images/osi-traffic-participant-use-case-1.png similarity index 100% rename from _static/images/osi-traffic-participant-use-case-1.png rename to content/_static/images/osi-traffic-participant-use-case-1.png diff --git a/_static/images/osi-traffic-participant-use-case-2.png b/content/_static/images/osi-traffic-participant-use-case-2.png similarity index 100% rename from _static/images/osi-traffic-participant-use-case-2.png rename to content/_static/images/osi-traffic-participant-use-case-2.png diff --git a/_static/images/osi-traffic-participant-use-case-3.png b/content/_static/images/osi-traffic-participant-use-case-3.png similarity index 100% rename from _static/images/osi-traffic-participant-use-case-3.png rename to content/_static/images/osi-traffic-participant-use-case-3.png diff --git a/_static/images/osi-traffic-participant-use-case-4.png b/content/_static/images/osi-traffic-participant-use-case-4.png similarity index 100% rename from _static/images/osi-traffic-participant-use-case-4.png rename to content/_static/images/osi-traffic-participant-use-case-4.png diff --git a/_static/images/osilogo.png b/content/_static/images/osilogo.png similarity index 100% rename from _static/images/osilogo.png rename to content/_static/images/osilogo.png diff --git a/appendix/releases/compatibility.adoc b/content/appendix/releases/compatibility.adoc similarity index 86% rename from appendix/releases/compatibility.adoc rename to content/appendix/releases/compatibility.adoc index c81058eb..73571095 100644 --- a/appendix/releases/compatibility.adoc +++ b/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. diff --git a/appendix/releases/v02.00.adoc b/content/appendix/releases/v02.00.adoc similarity index 87% rename from appendix/releases/v02.00.adoc rename to content/appendix/releases/v02.00.adoc index 65d0d0a3..c1fab079 100644 --- a/appendix/releases/v02.00.adoc +++ b/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). diff --git a/appendix/releases/v02.01.adoc b/content/appendix/releases/v02.01.adoc similarity index 62% rename from appendix/releases/v02.01.adoc rename to content/appendix/releases/v02.01.adoc index 13d2d25d..d287f63b 100644 --- a/appendix/releases/v02.01.adoc +++ b/content/appendix/releases/v02.01.adoc @@ -1,6 +1,14 @@ - - +ifndef::include-only-once[] +:root-path: ../../ +include::{root-path}_config.adoc[] +endif::[] +ifdef::use-antora-rules[] +:reftext: v2.1.0 - OSI "Agile Andretti" += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.1.0[{reftext}] +endif::[] +ifndef::use-antora-rules[] = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.1.0[v2.1.0 - OSI "Agile Andretti"] +endif::[] *Purpose* diff --git a/appendix/releases/v02.02.adoc b/content/appendix/releases/v02.02.00.adoc similarity index 58% rename from appendix/releases/v02.02.adoc rename to content/appendix/releases/v02.02.00.adoc index 5ea3a328..cd6c5052 100644 --- a/appendix/releases/v02.02.adoc +++ b/content/appendix/releases/v02.02.00.adoc @@ -1,6 +1,14 @@ - - -= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.2.0[v2.2.0 - OSI "Brave Brabham"] +ifndef::include-only-once[] +:root-path: ../../ +include::{root-path}_config.adoc[] +endif::[] +ifdef::use-antora-rules[] +:reftext: v2.2.0 - OSI "Brave Brabham"4 += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.2.0[{reftext}] +endif::[] +ifndef::use-antora-rules[] += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.2.0[v2.2.0 - OSI "Brave Brabham"4] +endif::[] *Purpose* @@ -15,14 +23,3 @@ This release focuses on optimizing the build process and documentation. * Redefined precipitation and added a fog definition to the environmental conditions message. * Added layer id to low level point cloud data. * Reworked large parts of the build instructions in the WIKI. - -= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.2.1[v2.2.1 - OSI "Brave Brabham", Update 1] - -*Purpose* - -This release focuses on optimizing the build process and ensures the proper installation of different versions of OSI on a single system. - -*https://github.com/OpenSimulationInterface/open-simulation-interface/compare/maintenance/v2.2.x[Content/Changes]* - -* Allowing several OSI versions on the same computer. -* Improves CI builds to also test the installation cmake targets for proper completion. diff --git a/content/appendix/releases/v02.02.01.adoc b/content/appendix/releases/v02.02.01.adoc new file mode 100644 index 00000000..37b487dd --- /dev/null +++ b/content/appendix/releases/v02.02.01.adoc @@ -0,0 +1,20 @@ +ifndef::include-only-once[] +:root-path: ../../ +include::{root-path}_config.adoc[] +endif::[] +ifdef::use-antora-rules[] +:reftext: v2.2.1 - OSI "Brave Brabham", Update 1 += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.2.1[{reftext}] +endif::[] +ifndef::use-antora-rules[] += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.2.1[v2.2.1 - OSI "Brave Brabham", Update 1] +endif::[] + +*Purpose* + +This release focuses on optimizing the build process and ensures the proper installation of different versions of OSI on a single system. + +*https://github.com/OpenSimulationInterface/open-simulation-interface/compare/maintenance/v2.2.x[Content/Changes]* + +* Allowing several OSI versions on the same computer. +* Improves CI builds to also test the installation cmake targets for proper completion. diff --git a/appendix/releases/v03.00.adoc b/content/appendix/releases/v03.00.00.adoc similarity index 72% rename from appendix/releases/v03.00.adoc rename to content/appendix/releases/v03.00.00.adoc index dde9b0fd..ef944ece 100644 --- a/appendix/releases/v03.00.adoc +++ b/content/appendix/releases/v03.00.00.adoc @@ -1,6 +1,14 @@ - - +ifndef::include-only-once[] +:root-path: ../../ +include::{root-path}_config.adoc[] +endif::[] +ifdef::use-antora-rules[] +:reftext: v3.0.0 - OSI "Cosmic Coulthard" += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.0.0[{reftext}] +endif::[] +ifndef::use-antora-rules[] = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.0.0[v3.0.0 - OSI "Cosmic Coulthard"] +endif::[] *Purpose* @@ -37,23 +45,3 @@ We are aligned with the ongoing discussions for the upcoming ISO 23150 cite:[iso * AND MUCH MORE ENJOY!!! https://github.com/OpenSimulationInterface/open-simulation-interface/files/2297162/osi_overview_v2.2_vs_v3.0.pdf>[See for more information the `changelog`] - -= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.0.1[v3.0.1 - OSI "Cosmic Coulthard", Update 1] - -https://www.youtube.com/watch?v=yG0oBPtyNb0[Summertime :)] - -*Purpose* - -This release is a patch reworking parts of the documentation in order to avoid ambiguities and improving the build/installation process of OSI. - -*https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?page=1&q=is%3Apr+is%3Aclosed+milestone%3Av3.0.1[Content/Changes]* - -* Added script to automatically convert the messages from proto2 to proto3 with on the wire compatibility -* cmake enhancements to enable multi-version support of OSI 2 and OSI 3 -* Added Python 3 support -* Clarification of multiple comments -* Added explanatory images in the documentation -* centerline definition improved -* signal_strength definition in LidarSensorView corrected -* FeatureData::ambiguity_id definition clarified -* RadarSensorViewConfiguration::AntennaDiagram::response definition clarified diff --git a/content/appendix/releases/v03.00.01.adoc b/content/appendix/releases/v03.00.01.adoc new file mode 100644 index 00000000..a5be04d8 --- /dev/null +++ b/content/appendix/releases/v03.00.01.adoc @@ -0,0 +1,29 @@ +ifndef::include-only-once[] +:root-path: ../../ +include::{root-path}_config.adoc[] +endif::[] +ifdef::use-antora-rules[] +:reftext: v3.0.1 - OSI "Cosmic Coulthard", Update 1 += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.0.1[{reftext}] +endif::[] +ifndef::use-antora-rules[] += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.0.1[v3.0.1 - OSI "Cosmic Coulthard", Update 1] +endif::[] + +https://www.youtube.com/watch?v=yG0oBPtyNb0[Summertime :)] + +*Purpose* + +This release is a patch reworking parts of the documentation in order to avoid ambiguities and improving the build/installation process of OSI. + +*https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?page=1&q=is%3Apr+is%3Aclosed+milestone%3Av3.0.1[Content/Changes]* + +* Added script to automatically convert the messages from proto2 to proto3 with on the wire compatibility +* cmake enhancements to enable multi-version support of OSI 2 and OSI 3 +* Added Python 3 support +* Clarification of multiple comments +* Added explanatory images in the documentation +* centerline definition improved +* signal_strength definition in LidarSensorView corrected +* FeatureData::ambiguity_id definition clarified +* RadarSensorViewConfiguration::AntennaDiagram::response definition clarified diff --git a/appendix/releases/v03.01.adoc b/content/appendix/releases/v03.01.00.adoc similarity index 61% rename from appendix/releases/v03.01.adoc rename to content/appendix/releases/v03.01.00.adoc index a6450d11..38611ddc 100644 --- a/appendix/releases/v03.01.adoc +++ b/content/appendix/releases/v03.01.00.adoc @@ -1,6 +1,14 @@ - - +ifndef::include-only-once[] +:root-path: ../../ +include::{root-path}_config.adoc[] +endif::[] +ifdef::use-antora-rules[] +:reftext: v3.1.0 - OSI "Dynamic Duncan" += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.0[{reftext}] +endif::[] +ifndef::use-antora-rules[] = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.0[v3.1.0 - OSI "Dynamic Duncan"] +endif::[] https://www.youtube.com/watch?v=fu3uA8K6ApQ>[(O SI)lent night] @@ -24,16 +32,3 @@ Trust me - it's amazing! * Added proj4 string for coordinate transformations. * Introduced raster_lidar_proposal from innoviz. * Improved documentation with HTML tables and images for all traffic signs. - -= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.1[v3.1.1 - OSI "Dynamic Duncan", Update 1] - -*https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.1[Content/Changes]* - -* **Bug Fix**: Changed open_simulation_interface target back from being a static library to a shared library, as before (this reverts an inadvertent change in v3.1.0 from previous releases). -v3.1.0 breaks all users of the shared library (i.e. everyone building on Linux/Unix systems, and even some using the DLL on Windows). - -= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.2[v3.1.2 - OSI "Dynamic Duncan", Update 2] - -*https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.2[Content/Changes]* - -* **Bugfix**: The version number is now correct in the VERSION file. diff --git a/content/appendix/releases/v03.01.01.adoc b/content/appendix/releases/v03.01.01.adoc new file mode 100644 index 00000000..570b4bbb --- /dev/null +++ b/content/appendix/releases/v03.01.01.adoc @@ -0,0 +1,16 @@ +ifndef::include-only-once[] +:root-path: ../../ +include::{root-path}_config.adoc[] +endif::[] +ifdef::use-antora-rules[] +:reftext: v3.1.1 - OSI "Dynamic Duncan", Update 1 += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.1[{reftext}] +endif::[] +ifndef::use-antora-rules[] += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.1[v3.1.1 - OSI "Dynamic Duncan", Update 1] +endif::[] + +*https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.1[Content/Changes]* + +* **Bug Fix**: Changed open_simulation_interface target back from being a static library to a shared library, as before (this reverts an inadvertent change in v3.1.0 from previous releases). +v3.1.0 breaks all users of the shared library (i.e. everyone building on Linux/Unix systems, and even some using the DLL on Windows). diff --git a/content/appendix/releases/v03.01.02.adoc b/content/appendix/releases/v03.01.02.adoc new file mode 100644 index 00000000..f59dfbb1 --- /dev/null +++ b/content/appendix/releases/v03.01.02.adoc @@ -0,0 +1,15 @@ +ifndef::include-only-once[] +:root-path: ../../ +include::{root-path}_config.adoc[] +endif::[] +ifdef::use-antora-rules[] +:reftext: v3.1.2 - OSI "Dynamic Duncan", Update 2 += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.2[{reftext}] +endif::[] +ifndef::use-antora-rules[] += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.2[v3.1.2 - OSI "Dynamic Duncan", Update 2] +endif::[] + +*https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.2[Content/Changes]* + +* **Bugfix**: The version number is now correct in the VERSION file. diff --git a/appendix/releases/v03.02.adoc b/content/appendix/releases/v03.02.adoc similarity index 89% rename from appendix/releases/v03.02.adoc rename to content/appendix/releases/v03.02.adoc index e783f38c..a540094a 100644 --- a/appendix/releases/v03.02.adoc +++ b/content/appendix/releases/v03.02.adoc @@ -1,6 +1,14 @@ - - +ifndef::include-only-once[] +:root-path: ../../ +include::{root-path}_config.adoc[] +endif::[] +ifdef::use-antora-rules[] +:reftext: v3.2.0 - OSI "Editorial Eaton" += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.2.0[{reftext}] +endif::[] +ifndef::use-antora-rules[] = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.2.0[v3.2.0 - OSI "Editorial Eaton"] +endif::[] https://www.youtube.com/watch?v=SJUhlRoBL8M[Think p(OSI)tive!] diff --git a/appendix/releases/v03.03.adoc b/content/appendix/releases/v03.03.00.adoc similarity index 86% rename from appendix/releases/v03.03.adoc rename to content/appendix/releases/v03.03.00.adoc index 633e6e02..eed8bdf6 100644 --- a/appendix/releases/v03.03.adoc +++ b/content/appendix/releases/v03.03.00.adoc @@ -1,6 +1,14 @@ - - +ifndef::include-only-once[] +:root-path: ../../ +include::{root-path}_config.adoc[] +endif::[] +ifdef::use-antora-rules[] +:reftext: v3.3.0 - OSI "Fabulous Fangio" += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.3.0[{reftext}] +endif::[] +ifndef::use-antora-rules[] = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.3.0[v3.3.0 - OSI "Fabulous Fangio"] +endif::[] Stay p(OSI)tive! @@ -31,11 +39,3 @@ This minor release highlights the work that has been done on several working pac * Make handling of enums in rules check more robust, especially ones. * Set the default compiler to C++ 11 to support protobuf>3.6. - -= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.3.1[v3.3.1 - OSI "Fabulous Fangio", Update 1] - -*https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/18?closed=1[Content/Changes]* - -* **Bug Fix**: Fixed outdated version information in VERSION file in 3.3.0. -This led to wrong versioning in proto definitions and Doxygen documentation. -* **Bug Fix**: Removed outdated picture in README.md. diff --git a/content/appendix/releases/v03.03.01.adoc b/content/appendix/releases/v03.03.01.adoc new file mode 100644 index 00000000..fc29a555 --- /dev/null +++ b/content/appendix/releases/v03.03.01.adoc @@ -0,0 +1,17 @@ +ifndef::include-only-once[] +:root-path: ../../ +include::{root-path}_config.adoc[] +endif::[] +ifdef::use-antora-rules[] +:reftext: v3.3.1 - OSI "Fabulous Fangio", Update 1 += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.3.1[{reftext}] +endif::[] +ifndef::use-antora-rules[] += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.3.1[v3.3.1 - OSI "Fabulous Fangio", Update 1] +endif::[] + +*https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/18?closed=1[Content/Changes]* + +* **Bug Fix**: Fixed outdated version information in VERSION file in 3.3.0. +This led to wrong versioning in proto definitions and Doxygen documentation. +* **Bug Fix**: Removed outdated picture in README.md. diff --git a/appendix/releases/v03.04.adoc b/content/appendix/releases/v03.04.adoc similarity index 87% rename from appendix/releases/v03.04.adoc rename to content/appendix/releases/v03.04.adoc index 69d450c7..85a846e5 100644 --- a/appendix/releases/v03.04.adoc +++ b/content/appendix/releases/v03.04.adoc @@ -1,6 +1,14 @@ - - +ifndef::include-only-once[] +:root-path: ../../ +include::{root-path}_config.adoc[] +endif::[] +ifdef::use-antora-rules[] +:reftext: v3.4.0 - OSI "Gallant Glock" += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.4.0[{reftext}] +endif::[] +ifndef::use-antora-rules[] = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.4.0[v3.4.0 - OSI "Gallant Glock"] +endif::[] Stay p(OSI)tive! @@ -11,6 +19,7 @@ Moreover, this release provides a first glance on the on-going efforts for OSI's *https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/14?closed=1[Content/Changes]* +//tag::content[] Documentation Updates:: - Updated the documentation's structure and migrated it to AsciiDoc. - Updated the description of OSI's top level messages. @@ -29,4 +38,5 @@ Technical Updates:: - Extended LidarDetection message under feature data to include echo pulse width information to better support several sensor outputs that are currently on the market. - Extended OSI to include a generic external reference message to enable traceability for data from other standards, including other ASAM OpenX standards. - Added support for using OSI with Flatbuffers encoding for OSI messages instead of ProtoBuffers, in preparation for a potential switch of default encoding in a future major release. -- Extended LaneBoundary message to include additional types, to better align with ASAM OpenDRIVE. \ No newline at end of file +- Extended LaneBoundary message to include additional types, to better align with ASAM OpenDRIVE. +//end::content[] diff --git a/appendix/releases/v03.05.adoc b/content/appendix/releases/v03.05.adoc similarity index 83% rename from appendix/releases/v03.05.adoc rename to content/appendix/releases/v03.05.adoc index b1e270ba..be6949ad 100644 --- a/appendix/releases/v03.05.adoc +++ b/content/appendix/releases/v03.05.adoc @@ -1,6 +1,14 @@ - - +ifndef::include-only-once[] +:root-path: ../../ +include::{root-path}_config.adoc[] +endif::[] +ifdef::use-antora-rules[] +:reftext: v3.5.0 - OSI "Hard-fighting Hunt" += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.5.0[{reftext}] +endif::[] +ifndef::use-antora-rules[] = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.5.0[v3.5.0 - OSI "Hard-fighting Hunt"] +endif::[] L(OSI)ng is not an option! diff --git a/contributing/branching_member.adoc b/content/contributing/branching_member.adoc similarity index 87% rename from contributing/branching_member.adoc rename to content/contributing/branching_member.adoc index 898e86a2..3f924c94 100644 --- a/contributing/branching_member.adoc +++ b/content/contributing/branching_member.adoc @@ -1,3 +1,7 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] = Branching workflow for member contributors Members of the OSI project can contribute to the ASAM OSI repositories directly. @@ -26,5 +30,5 @@ This label indicates that the changes in the pull request can be merged. **Related topics** -- <<_reporting_issues>> -- <<_guidelines_for_contributions>> \ No newline at end of file +- <> +- <> \ No newline at end of file diff --git a/contributing/commenting_fields_enums.adoc b/content/contributing/commenting_fields_enums.adoc similarity index 92% rename from contributing/commenting_fields_enums.adoc rename to content/contributing/commenting_fields_enums.adoc index 24b07ebe..7f8649ae 100644 --- a/contributing/commenting_fields_enums.adoc +++ b/content/contributing/commenting_fields_enums.adoc @@ -1,3 +1,8 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] +[#top-commenting_on_fields_and_enums] = Commenting on fields and enums The {THIS_STANDARD} reference documentation is created using _Doxygen_. @@ -56,4 +61,4 @@ message EnvironmentalConditions **Related topics** -- <<_guidelines_for_creating_literary_references>> \ No newline at end of file +- <> \ No newline at end of file diff --git a/contributing/commenting_messages.adoc b/content/contributing/commenting_messages.adoc similarity index 90% rename from contributing/commenting_messages.adoc rename to content/contributing/commenting_messages.adoc index 67424c52..73e18c1a 100644 --- a/contributing/commenting_messages.adoc +++ b/content/contributing/commenting_messages.adoc @@ -1,3 +1,8 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] +[#top-commenting_on_messages] = Commenting on messages The {THiS_STANDARD} reference documentation is created using _Doxygen_. diff --git a/contributing/contributing_docs.adoc b/content/contributing/contributing_docs.adoc similarity index 86% rename from contributing/contributing_docs.adoc rename to content/contributing/contributing_docs.adoc index de1bd6e6..bf05bac4 100644 --- a/contributing/contributing_docs.adoc +++ b/content/contributing/contributing_docs.adoc @@ -1,3 +1,7 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] = Contributing to the documentation Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. diff --git a/contributing/contribution_rules.adoc b/content/contributing/contribution_rules.adoc similarity index 72% rename from contributing/contribution_rules.adoc rename to content/contributing/contribution_rules.adoc index 9aea6940..13e6b07e 100644 --- a/contributing/contribution_rules.adoc +++ b/content/contributing/contribution_rules.adoc @@ -1,3 +1,8 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] +[#top-guidelines_for_contributions] = Guidelines for contributions Commit guidelines exist to ensure the transparency and intelligibility of the commit history. @@ -15,8 +20,8 @@ Commit guidelines exist to ensure the transparency and intelligibility of the co **Related topics** -- <<_guidelines_for_writing_commit_messages>> -- <<_interface_conventions>> -- <<_commenting_on_messages>> -- <<_commenting_on_fields_and_enums>> -- <<_signing_off_commits>> \ No newline at end of file +- <> +- <> +- <> +- <> +- <> \ No newline at end of file diff --git a/contributing/creating_images.adoc b/content/contributing/creating_images.adoc similarity index 86% rename from contributing/creating_images.adoc rename to content/contributing/creating_images.adoc index ad23656f..06610a8d 100644 --- a/contributing/creating_images.adoc +++ b/content/contributing/creating_images.adoc @@ -1,3 +1,7 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] = Creating vector images Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. diff --git a/contributing/creating_references.adoc b/content/contributing/creating_references.adoc similarity index 95% rename from contributing/creating_references.adoc rename to content/contributing/creating_references.adoc index e2e41bf4..e63deb3f 100644 --- a/contributing/creating_references.adoc +++ b/content/contributing/creating_references.adoc @@ -1,3 +1,8 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] +[#top-guidelines_for_creating_literary_references] = Guidelines for creating literary references When citing literature in the reference documentation, adhere to the following guidelines: diff --git a/contributing/dco.adoc b/content/contributing/dco.adoc similarity index 93% rename from contributing/dco.adoc rename to content/contributing/dco.adoc index a43aeba1..44b6a1d9 100644 --- a/contributing/dco.adoc +++ b/content/contributing/dco.adoc @@ -1,3 +1,8 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] +[#top-developer_certificate_of_origin_dco] = Developer Certificate of Origin (DCO) To make a good-faith effort to ensure licensing criteria are met, the Developer-Certificate-of-Origin (DCO) process shall be followed. diff --git a/contributing/forking_no_member.adoc b/content/contributing/forking_no_member.adoc similarity index 88% rename from contributing/forking_no_member.adoc rename to content/contributing/forking_no_member.adoc index 740adfc8..a0524980 100644 --- a/contributing/forking_no_member.adoc +++ b/content/contributing/forking_no_member.adoc @@ -1,3 +1,7 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] = Forking for non-member contributors External contributors must fork the OSI repositories and contribute their changes via a pull request. @@ -26,5 +30,5 @@ This label indicates that the changes in the pull request can be merged. **Related topics** -- <<_reporting_issues>> -- <<_guidelines_for_contributions>> \ No newline at end of file +- <> +- <> \ No newline at end of file diff --git a/contributing/licensing.adoc b/content/contributing/licensing.adoc similarity index 73% rename from contributing/licensing.adoc rename to content/contributing/licensing.adoc index 04ee6f46..66885083 100644 --- a/contributing/licensing.adoc +++ b/content/contributing/licensing.adoc @@ -1,3 +1,7 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] = License OSI uses the https://www.mozilla.org/en-US/MPL/2.0/[Mozilla Public License, v. 2.0]. diff --git a/contributing/naming_conventions.adoc b/content/contributing/naming_conventions.adoc similarity index 91% rename from contributing/naming_conventions.adoc rename to content/contributing/naming_conventions.adoc index 6af2b224..344009ef 100644 --- a/contributing/naming_conventions.adoc +++ b/content/contributing/naming_conventions.adoc @@ -1,3 +1,8 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] +[#top-interface_conventions] = Interface conventions OSI messages, enums, field messages, and field enums shall comply with OSI interface conventions. diff --git a/contributing/reporting_issues.adoc b/content/contributing/reporting_issues.adoc similarity index 84% rename from contributing/reporting_issues.adoc rename to content/contributing/reporting_issues.adoc index d0f5588e..3d7af80a 100644 --- a/contributing/reporting_issues.adoc +++ b/content/contributing/reporting_issues.adoc @@ -1,3 +1,8 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] +[#top-reporting_issues] = Reporting issues Reporting issues is a simple way of contributing to OSI. @@ -22,4 +27,4 @@ Reporting issues is a simple way of contributing to OSI. **Related topics** -- <<_asam_osi_repositories>> \ No newline at end of file +- <> \ No newline at end of file diff --git a/contributing/review_author.adoc b/content/contributing/review_author.adoc similarity index 77% rename from contributing/review_author.adoc rename to content/contributing/review_author.adoc index a4201781..af31c483 100644 --- a/contributing/review_author.adoc +++ b/content/contributing/review_author.adoc @@ -1,3 +1,7 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] = Review guidelines for authors Code review enhances the quality of the code and reduces the likelihood of introducing new bugs in the code base. @@ -15,6 +19,6 @@ Before asking for a review, make sure your changes meet the following requiremen **Related topics** -- <<_interface_conventions>> -- <<_guidelines_for_writing_commit_messages>> -- <<_signing_off_commits>> +- <> +- <> +- <> diff --git a/contributing/review_reviewer.adoc b/content/contributing/review_reviewer.adoc similarity index 96% rename from contributing/review_reviewer.adoc rename to content/contributing/review_reviewer.adoc index cc42a775..f0ded968 100644 --- a/contributing/review_reviewer.adoc +++ b/content/contributing/review_reviewer.adoc @@ -1,3 +1,7 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] = Review guidelines for reviewers Code reviews can be challenging at times. diff --git a/contributing/signing_off_commits.adoc b/content/contributing/signing_off_commits.adoc similarity index 77% rename from contributing/signing_off_commits.adoc rename to content/contributing/signing_off_commits.adoc index 1195d96d..0e67e574 100644 --- a/contributing/signing_off_commits.adoc +++ b/content/contributing/signing_off_commits.adoc @@ -1,3 +1,8 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] +[#top-signing_off_commits] = Signing off commits Contributing to OSI projects, it is necessary to agree to the Developer Certificate of Origin (DCO). @@ -18,4 +23,4 @@ git commit -m "Commit message" -s **Related topics** -- <<_developer_certificate_of_origin_dco>> \ No newline at end of file +- <> \ No newline at end of file diff --git a/contributing/start_contributing.adoc b/content/contributing/start_contributing.adoc similarity index 78% rename from contributing/start_contributing.adoc rename to content/contributing/start_contributing.adoc index 8d826be5..22746dd3 100644 --- a/contributing/start_contributing.adoc +++ b/content/contributing/start_contributing.adoc @@ -1,3 +1,7 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] = Getting started with contributing Before you start, familiarize yourself with {THIS_STANDARD} and how to contribute by reading this documentation and the reference documentation of {THIS_STANDARD}. diff --git a/contributing/writing_commit_messages.adoc b/content/contributing/writing_commit_messages.adoc similarity index 94% rename from contributing/writing_commit_messages.adoc rename to content/contributing/writing_commit_messages.adoc index ad0408cd..4c810f94 100644 --- a/contributing/writing_commit_messages.adoc +++ b/content/contributing/writing_commit_messages.adoc @@ -1,3 +1,8 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] +[#top-guidelines_for_writing_commit_messages] = Guidelines for writing commit messages Apart from a sign-off message, {THIS_STANDARD} requires commit messages to follow a specific format. diff --git a/content/general_docs/bibliography.adoc b/content/general_docs/bibliography.adoc new file mode 100644 index 00000000..a2a6f7dc --- /dev/null +++ b/content/general_docs/bibliography.adoc @@ -0,0 +1,6 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Bibliography +bibliography::[] \ No newline at end of file diff --git a/general_docs/bibliography.bib b/content/general_docs/bibliography.bib similarity index 100% rename from general_docs/bibliography.bib rename to content/general_docs/bibliography.bib diff --git a/content/general_docs/changes.adoc b/content/general_docs/changes.adoc new file mode 100644 index 00000000..7c36692c --- /dev/null +++ b/content/general_docs/changes.adoc @@ -0,0 +1,7 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += What has changed + +include::../appendix/releases/v03.04.adoc[tag=content] diff --git a/general_docs/conventions.adoc b/content/general_docs/conventions.adoc similarity index 79% rename from general_docs/conventions.adoc rename to content/general_docs/conventions.adoc index caf60766..b9e4c65c 100644 --- a/general_docs/conventions.adoc +++ b/content/general_docs/conventions.adoc @@ -1,17 +1,22 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] = Conventions == Units Every field has its own unit that is defined in the proto files. -For more information, see <<_commenting_on_fields_and_enums, the example in the contribution guidelines.>> +For more information, see <> [#sec-273d9649-afab-45d3-b6c9-73c0e64971a0] -include::../{asciidoc-resources}/modal_verbs.adoc[leveloffset=+1] +include::{asciidoc-resources}/modal_verbs.adoc[leveloffset=+1] == Typographic conventions This documentation uses the following typographical conventions: +[#tab-typographical-conventions] .Typographical conventions [%header, cols=2*] |=== diff --git a/general_docs/deliverables.adoc b/content/general_docs/deliverables.adoc similarity index 60% rename from general_docs/deliverables.adoc rename to content/general_docs/deliverables.adoc index 9f996037..a247d570 100644 --- a/general_docs/deliverables.adoc +++ b/content/general_docs/deliverables.adoc @@ -1,13 +1,17 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] = Deliverables The following deliverables are provided for {THIS_STANDARD}: * User guide, that is, this document (partly normative) * .proto files (normative) -* Doxygen reference documentation (not normative) +* xref:gen:index.adoc[Doxygen reference documentation] (not normative) * OSMP packaging (OSMP packaging has its own version number, but is compatible with the version of {THIS_STANDARD}.) **Related topics** -- <<_normative_and_non_normative_statements>> +- <> - <> \ No newline at end of file diff --git a/general_docs/foreword.adoc b/content/general_docs/foreword.adoc similarity index 94% rename from general_docs/foreword.adoc rename to content/general_docs/foreword.adoc index 3c632f68..7350ecec 100644 --- a/general_docs/foreword.adoc +++ b/content/general_docs/foreword.adoc @@ -1,3 +1,7 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] = Foreword The {THIS_STANDARD} (Open Simulation Interface) is a specification for interfaces between models and components of a distributed simulation. diff --git a/general_docs/glossary.adoc b/content/general_docs/glossary.adoc similarity index 97% rename from general_docs/glossary.adoc rename to content/general_docs/glossary.adoc index 888a5c7f..57f29aea 100644 --- a/general_docs/glossary.adoc +++ b/content/general_docs/glossary.adoc @@ -1,3 +1,7 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] [glossary] = Terms and definitions diff --git a/general_docs/osi_repos.adoc b/content/general_docs/osi_repos.adoc similarity index 90% rename from general_docs/osi_repos.adoc rename to content/general_docs/osi_repos.adoc index 52b5ed6d..dfbeebd6 100644 --- a/general_docs/osi_repos.adoc +++ b/content/general_docs/osi_repos.adoc @@ -1,6 +1,9 @@ - +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] [#top-repositories] -= {THIS_STANDARD} repositories += {THIS_STANDARD_TITLE} repositories {THIS_STANDARD} is an open-source standardization project. OSI and its supporting tools are developed publicly on GitHub. diff --git a/general_docs/statements.adoc b/content/general_docs/statements.adoc similarity index 69% rename from general_docs/statements.adoc rename to content/general_docs/statements.adoc index 674a8aba..bf5231a5 100644 --- a/general_docs/statements.adoc +++ b/content/general_docs/statements.adoc @@ -1,9 +1,15 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] +[#top-normative_and_non_normative_statements] = Normative and non-normative statements + This specification uses a standard information structure. The following rules apply regarding normativity of the different sections: -* Statements expressed as requirements, permissions, or prohibitions according to the use of modal verbs, as defined in <>, are normative. +* Statements expressed as requirements, permissions, or prohibitions according to the use of modal verbs, as defined in <>, are normative. * Rules in "Rules" sections are normative. * .proto files are normative. * Examples, use case descriptions, and instructions are non-normative. diff --git a/general_docs/versioning.adoc b/content/general_docs/versioning.adoc similarity index 89% rename from general_docs/versioning.adoc rename to content/general_docs/versioning.adoc index f8d347b4..8115174b 100644 --- a/general_docs/versioning.adoc +++ b/content/general_docs/versioning.adoc @@ -1,8 +1,12 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] = Versioning and compatibility The version number is defined in `InterfaceVersion::version_number` in `osi_version.proto` as the field's default value. -OSI uses https://semver.org/[Semantic Versioning]. +OSI uses https://semver.org/[Semantic Versioning^]. Major:: A change in the major version makes the code and recorded proto messages incompatible. diff --git a/general_standard/relations_to_other_standards.adoc b/content/general_standard/relations_to_other_standards.adoc similarity index 93% rename from general_standard/relations_to_other_standards.adoc rename to content/general_standard/relations_to_other_standards.adoc index 7319e6c9..d855901c 100644 --- a/general_standard/relations_to_other_standards.adoc +++ b/content/general_standard/relations_to_other_standards.adoc @@ -1,3 +1,7 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] = Relationships with other standards == Positioning of {THIS_STANDARD} within ASAM activities diff --git a/index.adoc b/content/index.adoc similarity index 66% rename from index.adoc rename to content/index.adoc index 29318b62..d6e2b638 100644 --- a/index.adoc +++ b/content/index.adoc @@ -1,35 +1,5 @@ - -:THIS_STANDARD: ASAM OSI® - -:asciidoc-resources: ./asciidoc-resources -include::{asciidoc-resources}/preamble.adoc[] - -:revnumber: --localbuild-- -:revdate: {docdate} - -:topicdir: topics -:reusedir: reuse - -// as decided in the project -:toclevels: 3 -:xrefstyle: full - -//embed images into html -:imagesdir: . -// 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_open_simulation_interface: ./open-simulation-interface/doc/images -// :images_osi_sensor_model_packaging: ./osi-sensor-model-packaging/doc/images // example - -:imagesoutdir: ./images/generated_images - -// attention: bibtex requires pathing relative to asciidoc command, not main.adoc! -:bibtex-file: ./general_docs/bibliography.bib - - - +:root-path: +include::{root-path}_config.adoc[] = {THIS_STANDARD} (Open Simulation Interface) [IMPORTANT] @@ -39,9 +9,18 @@ This document is the copyrighted property of ASAM e.V. Any use is limited to the scope described in the https://www.asam.net/license[license terms]. ==== +ifndef::use-antora-rules[] +:asciidoc-resources: ../{asciidoc-resources} <<< toc::[] +endif::[] + +[preface] +include::./general_docs/foreword.adoc[leveloffset=+1] + + +ifndef::use-antora-rules[] [foreword] include::./general_docs/foreword.adoc[leveloffset=+1] @@ -64,9 +43,9 @@ include::./general_standard/relations_to_other_standards.adoc[leveloffset=+2] // START: including the documentation of other osi repositories -include::./open-simulation-interface/doc/open-simulation-interface_user_guide.adoc[leveloffset=+1] +include::{doc_open_simulation_interface}open-simulation-interface_user_guide.adoc[leveloffset=+1] -include::./osi-sensor-model-packaging/doc/osi-sensor-model-packaging_spec.adoc[leveloffset=+1] +include::{doc_osi-sensor-model-packaging}osi-sensor-model-packaging_spec.adoc[leveloffset=+1] // osi-validation and osi-visualizer are considered supplementary tooling that is not normative. They are therefore not part of the ASAM standard release. // include::./osi-validation/doc/osi-validator_user_guide.adoc[leveloffset=+1,opts=optional] @@ -130,19 +109,19 @@ bibliography::[] == Release Notes :sectnums!: +include::./appendix/releases/v03.05.adoc[leveloffset=+2] include::./appendix/releases/v03.04.adoc[leveloffset=+2] -include::./appendix/releases/v03.03.adoc[leveloffset=+2] +include::./appendix/releases/v03.03.01.adoc[leveloffset=+2] +include::./appendix/releases/v03.03.00.adoc[leveloffset=+2] include::./appendix/releases/v03.02.adoc[leveloffset=+2] -include::./appendix/releases/v03.01.adoc[leveloffset=+2] -include::./appendix/releases/v03.00.adoc[leveloffset=+2] -include::./appendix/releases/v02.02.adoc[leveloffset=+2] +include::./appendix/releases/v03.01.02.adoc[leveloffset=+2] +include::./appendix/releases/v03.01.01.adoc[leveloffset=+2] +include::./appendix/releases/v03.01.00.adoc[leveloffset=+2] +include::./appendix/releases/v03.00.01.adoc[leveloffset=+2] +include::./appendix/releases/v03.00.00.adoc[leveloffset=+2] +include::./appendix/releases/v02.02.01.adoc[leveloffset=+2] +include::./appendix/releases/v02.02.00.adoc[leveloffset=+2] include::./appendix/releases/v02.01.adoc[leveloffset=+2] include::./appendix/releases/v02.00.adoc[leveloffset=+2] - - - - - - - +endif::[] diff --git a/docker-compose.yml b/docker-compose.yml index 0af36db2..e92dd88c 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -6,4 +6,4 @@ services: volumes: - .:/documents working_dir: /documents - entrypoint: asciidoctor -D . --failure-level WARN -r asciidoctor-bibtex -r asciidoctor-diagram -a mathjax --trace --backend=html5 index.adoc -o open-simulation-interface_localbuild.html \ No newline at end of file + entrypoint: asciidoctor -D . --failure-level WARN -r asciidoctor-bibtex -r asciidoctor-diagram -a mathjax --trace --backend=html5 content/index.adoc -o open-simulation-interface_localbuild.html \ No newline at end of file diff --git a/general_docs/changes.adoc b/general_docs/changes.adoc deleted file mode 100644 index fb94e1a7..00000000 --- a/general_docs/changes.adoc +++ /dev/null @@ -1,3 +0,0 @@ -= What has changed - -include::../appendix/releases/v03.04.adoc[lines=14..50] diff --git a/local_build_tools/asciidoctor.bat b/local_build_tools/asciidoctor.bat new file mode 100644 index 00000000..a5dd7d2a --- /dev/null +++ b/local_build_tools/asciidoctor.bat @@ -0,0 +1,3 @@ +@ECHO OFF +docker-compose up -d +PAUSE \ No newline at end of file diff --git a/local_build_tools/compose.yml b/local_build_tools/compose.yml new file mode 100644 index 00000000..a37849c1 --- /dev/null +++ b/local_build_tools/compose.yml @@ -0,0 +1,8 @@ +version: "2" + +services: + asciidoctor: + image: asciidoctor/docker-asciidoctor + volumes: + - ../:/documents + entrypoint: asciidoctor --failure-level WARN -r asciidoctor-kroki -a mathjax -r asciidoctor-bibtex --trace content/index.adoc -o local_build_tools/HTML_content_local_build.html \ No newline at end of file diff --git a/local_build_tools/windows_convert_symlinks(ADMIN).bat b/local_build_tools/windows_convert_symlinks(ADMIN).bat new file mode 100644 index 00000000..a6c0463b --- /dev/null +++ b/local_build_tools/windows_convert_symlinks(ADMIN).bat @@ -0,0 +1,13 @@ +@ECHO OFF +SET Targetpath=..\.antora\modules\specification +SET Symlinkroot=..\..\.. + +mklink /D %Targetpath%\images %Symlinkroot%\content\_static\images + +mklink /D %Targetpath%\pages %Symlinkroot%\content + +@REM mklink /D %Targetpath%\partials %Symlinkroot%\_additional_content + +@REM mklink /D %Targetpath%\attachments %Symlinkroot%\_attachments + +PAUSE \ No newline at end of file