Skip to content

Commit 6962852

Browse files
philipwindeckerphilipwindecker
authored
Merge pull request #55 from OpenSimulationInterface/antora/base-antora-setup
Build: Create base Antora setup
2 parents bc93f0b + 47d64e0 commit 6962852

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

67 files changed

+674
-160
lines changed

‎.antora/antora.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Component name (without spaces!). All content repositories with the same component name are merged in Antora.
2+
name: asamosi
3+
# CENTRAL DOCUMENT ONLY!!! Display name of the component. Define only once per component!
4+
title: ASAM OSI
5+
version:
6+
# Update version number accordingly. This is the version for the main branch
7+
main: 'current'
8+
v(*)-antora: V$1
9+
v(*): V$1
10+
V(*): V$1
11+
# 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/")
12+
(*): 'V3.6.0-$1'
13+
# CENTRAL DOCUMENT ONLY!!! First page of the component. Define only once per component!
14+
start_page: specification:index.adoc
15+
16+
# THE FOLLOWING MAY ONLY DEFINED FOR THE CENTRAL DOCUMENT!!!
17+
asciidoc: # Sets global AsciiDoc attributes that are applied for every page of this component (from all repositories with the same version and component name!)
18+
attributes:
19+
# START - Mandatory ASAM attributes
20+
use-antora-rules: true
21+
THIS_STANDARD: ASAM OSI<sup>®</sup> # Normal attribute
22+
THIS_STANDARD_TITLE: 'ASAM OSI^®^' # Normal attribute
23+
# THIS_STANDARD: ASAM OSI # PDF version attribute
24+
# THIS_STANDARD_TITLE: 'ASAM OSI' # PDF version attribute
25+
partials-path: partial$
26+
root-path: page$
27+
appendix-caption: Annex
28+
# appendix-offset: 1
29+
asam-terminology: v0.0.1@ASAM_Terminology:ROOT:partial$terms_and_definitions_opendrive.adoc
30+
topicdir: topics
31+
reusedir: reuse
32+
imagesoutdir: ./images/generated_images
33+
images_open_simulation_interface: 'interface:'
34+
doc_open_simulation_interface: 'interface:'
35+
doc_osi-sensor-model-packaging: 'sensor-model:'
36+
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"]]
37+
38+
# END - Mandatory ASAM attributes
39+
# doxygen_interface_version: "v3.2.0" # The interface version that needs to be retrieved
40+
# doxygen_document_date: "01.01.2000" # The date associated with the document (optional)
41+
doxygen_module: "gen" # The module in which the output is stored
42+
# doxygen_module_path: "gen" # Path within module
43+
44+
nav:
45+
- modules/specification/nav_introduction.adoc
46+
- modules/interface/nav.adoc
47+
- modules/sensor-model/nav.adoc
48+
- modules/specification/nav_contribution.adoc
49+
- modules/gen/doxynav.adoc
50+
- modules/specification/nav_loft.adoc
51+
# Add more items here as required.
52+
# Recommended: One navigation file per document/repository!
53+
# Recommended: Name your module (folder) as your document type, e.g. "standard" or "concept" or "topic-guidelines"
54+
# Format: - modules/<module-folder-name>/<navigation-file-name>.adoc

‎.antora/modules/specification/images‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../content/_static/images

‎.antora/modules/specification/nav_contribution.adoc‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
* Contributing to ASAM OSI
2+
3+
** xref:contributing/start_contributing.adoc[]
4+
5+
** xref:contributing/reporting_issues.adoc[]
6+
7+
** Contributing changes
8+
9+
*** xref:contributing/licensing.adoc[]
10+
11+
*** xref:contributing/dco.adoc[]
12+
13+
*** xref:contributing/signing_off_commits.adoc[]
14+
15+
*** xref:contributing/writing_commit_messages.adoc[]
16+
17+
*** xref:contributing/contribution_rules.adoc[]
18+
19+
*** xref:contributing/naming_conventions.adoc[]
20+
21+
*** xref:contributing/branching_member.adoc[]
22+
23+
*** xref:contributing/forking_no_member.adoc[]
24+
25+
// *** xref:contributing/contributing_docs.adoc[]
26+
27+
*** xref:contributing/commenting_messages.adoc[]
28+
29+
*** xref:contributing/commenting_fields_enums.adoc[]
30+
31+
*** xref:contributing/creating_references.adoc[]
32+
33+
// *** xref:contributing/creating_images.adoc[]
34+
35+
** Reviewing contributions
36+
37+
*** xref:contributing/review_author.adoc[]
38+
39+
*** xref:contributing/review_reviewer.adoc[]
40+
41+
[glossary]
42+
* xref:general_docs/glossary.adoc[]
43+
44+
45+
[bibliography]
46+
* xref:general_docs/bibliography.adoc[]
47+
48+
[appendix]
49+
* Release Notes
50+
51+
:sectnums!:
52+
** xref:appendix/releases/v03.04.adoc[]
53+
:sectnums!:
54+
** xref:appendix/releases/v03.03.01.adoc[]
55+
:sectnums!:
56+
** xref:appendix/releases/v03.03.00.adoc[]
57+
:sectnums!:
58+
** xref:appendix/releases/v03.02.adoc[]
59+
:sectnums!:
60+
** xref:appendix/releases/v03.01.02.adoc[]
61+
:sectnums!:
62+
** xref:appendix/releases/v03.01.01.adoc[]
63+
:sectnums!:
64+
** xref:appendix/releases/v03.01.00.adoc[]
65+
:sectnums!:
66+
** xref:appendix/releases/v03.00.01.adoc[]
67+
:sectnums!:
68+
** xref:appendix/releases/v03.00.00.adoc[]
69+
:sectnums!:
70+
** xref:appendix/releases/v02.02.01.adoc[]
71+
:sectnums!:
72+
** xref:appendix/releases/v02.02.00.adoc[]
73+
:sectnums!:
74+
** xref:appendix/releases/v02.01.adoc[]
75+
:sectnums!:
76+
** xref:appendix/releases/v02.00.adoc[]

‎.antora/modules/specification/nav_introduction.adoc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
2+
* Introduction
3+
** xref:general_docs/changes.adoc[]
4+
** xref:general_docs/deliverables.adoc[]
5+
** xref:general_docs/osi_repos.adoc[]
6+
** xref:general_docs/statements.adoc[]
7+
** xref:general_docs/conventions.adoc[]
8+
** xref:general_docs/versioning.adoc[]
9+
** xref:general_standard/relations_to_other_standards.adoc[]

‎.antora/modules/specification/nav_loft.adoc‎

Whitespace-only changes.

‎.antora/modules/specification/pages‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../content

‎.github/workflows/antora-build.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Antora Documentation Build
2+
3+
on:
4+
# create: # new branches or tags
5+
# release: # new releases
6+
push:
7+
branches-ignore: [ main, master ]
8+
# push: # on push. This may be removed later
9+
# schedule: # periodic - needed because some of the content is from the other repos
10+
# - cron: '30 5,20 * * *' # this is pretty often. Only needed during review phase
11+
12+
jobs:
13+
antora-build:
14+
name: Build
15+
runs-on: ubuntu-20.04
16+
17+
services:
18+
kroki:
19+
image: yuzutech/kroki:0.15.1
20+
env:
21+
KROKI_MAX_URI_LENGTH: 8000
22+
KROKI_BLOCKDIAG_HOST: blockdiag
23+
KROKI_MERMAID_HOST: mermaid
24+
blockdiag:
25+
image: yuzutech/kroki-blockdiag:0.15.1
26+
mermaid:
27+
image: yuzutech/kroki-mermaid:0.15.1
28+
29+
steps:
30+
- name: Checkout generator
31+
uses: actions/checkout@master
32+
with:
33+
repository: OpenSimulationInterface/osi-antora-generator
34+
path: generator
35+
submodules: true
36+
fetch-depth: 0
37+
38+
- name: Modify site.yml
39+
working-directory: generator
40+
run: |
41+
echo "$GITHUB_REF_NAME"
42+
sed -i -E "s%(branches\:) \[antora\/base-antora-setup\] \# osi-documentation%\1 [$GITHUB_REF_NAME] \# osi-documentation%" site.yml
43+
cat site.yml
44+
sed -i -E "s/cd repo/cd generator/" run-build.sh
45+
cat run-build.sh
46+
47+
- name: Generate site
48+
uses: docker://ghcr.io/asam-ev/project-guide-docker:4
49+
with:
50+
entrypoint: sh
51+
args: generator/run-build.sh
52+
53+
- name: Upload artifact
54+
uses: actions/upload-artifact@v3
55+
with:
56+
name: antora-build
57+
path: ./generator/site
58+
59+

‎.github/workflows/asciidoc-build.yml‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -28,15 +28,15 @@ jobs:
2828
uses: actions/checkout@v2
2929
with:
3030
repository: OpenSimulationInterface/open-simulation-interface
31-
path: open-simulation-interface
31+
path: content/open-simulation-interface
3232
fetch-depth: 0
3333

3434

3535
- name: Checkout OSI Sensor Model Packaging
3636
uses: actions/checkout@v2
3737
with:
3838
repository: OpenSimulationInterface/osi-sensor-model-packaging
39-
path: osi-sensor-model-packaging
39+
path: content/osi-sensor-model-packaging
4040

4141
- name: Checkout proto2cpp
4242
uses: actions/checkout@v2
@@ -47,24 +47,24 @@ jobs:
4747
# Versioning
4848
- name: Get versioning
4949
id: get_version
50-
working-directory: open-simulation-interface
50+
working-directory: content/open-simulation-interface
5151
run: echo ::set-output name=VERSION::$(git describe --always)
5252

5353
# replaces the placeholder for versioning in the main mapping file
5454
- name: Apply versioning to Adoc
5555
run: |
56-
grep ":revnumber:" index.adoc
57-
sed -i -e "s/--localbuild--/master (${{ steps.get_version.outputs.VERSION }})/" index.adoc
58-
grep ":revnumber:" index.adoc
56+
grep ":revnumber:" content/_config.adoc
57+
sed -i -e "s/--localbuild--/main (${{ steps.get_version.outputs.VERSION }})/" content/_config.adoc
58+
grep ":revnumber:" content/_config.adoc
5959
6060
- name: Remove docdate for online hosted document
61-
run: sed 's/^:revdate:.*/:!revdate:/' index.adoc
61+
run: sed 's/^:revdate:.*/:!revdate:/' content/_config.adoc
6262

6363
# run Asciidoctor
6464
- name: Build HTML
6565
uses: avattathil/asciidoctor-action@master
6666
with:
67-
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"
67+
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"
6868

6969
# Upload artifact.
7070
- name: Upload HTML Artifact

‎README.adoc‎

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,39 @@
11
= OSI Documentation
22

3-
This repo hosts the asciidoc-based part of the documentation.
4-
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].
3+
This repo hosts the AsciiDoc-based part of the documentation.
4+
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].
5+
6+
// TODO: Update if Asciidoctor is completely dropped!
57

68
== ASAM OSI (R) official documentation
79

810
See the documentation https://opensimulationinterface.github.io/osi-documentation/[here].
911

1012

11-
== Build Pipeline
12-
13+
== Build pipeline
14+
=== Asciidoctor pipeline
1315

1416
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]
1517

18+
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.
19+
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].
20+
21+
=== Antora pipeline
22+
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]
1623

17-
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].
24+
NOTE: This pipeline runs on https://github.com/OpenSimulationInterface/osi-antora-generator.
1825

1926

2027
== How To build and change documentation locally
2128

22-
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.
29+
IMPORTANT: These instructions relate ONLY to the Asciidoctor build.
30+
For Antora, check the https://github.com/OpenSimulationInterface/osi-antora-generator[ASAM OSI Antora generator].
31+
32+
33+
The following instructions show how to build the document locally.
34+
Take note that the document is built with a version 'localbuild' in the document and filename.
2335

24-
The instruction should work on Windows, Linux and MacOS.
36+
The instruction should work on Windows, Linux, and MacOS.
2537

2638
. *Precondition*: have docker and docker-compose installed.
2739
+

‎content/_config.adoc‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
2+
// This file contains AsciiDoc attributes that shall be used in every AsciiDoc file.
3+
// NOTE: Its content is only applied for Asciidoctor!
4+
// If the same attribute is defined in the antora.yml (without @), the antora.yml definition takes precedence for Antora.
5+
6+
ifndef::root-path[:root-path: ./]
7+
8+
:asciidoc-resources: {root-path}../asciidoc-resources
9+
// :asciidoc-resources: ../asciidoc-resources
10+
:appendix-caption: Annex
11+
12+
// ifndef::use-antora-rules,include-only-once[]
13+
ifndef::include-only-once[]
14+
:GLO_VAR_STA_ASAM_OpenCRG: ASAM OpenCRG
15+
:glo_var_sta_asam_opencrg: {GLO_VAR_STA_ASAM_OpenCRG}
16+
:GLO_VAR_STA_ASAM_OpenDRIVE: ASAM OpenDRIVE
17+
:GLO_VAR_STA_ASAM_OpenLABEL: ASAM OpenLABEL
18+
:GLO_VAR_STA_ASAM_OpenODD: ASAM OpenODD
19+
:GLO_VAR_STA_ASAM_OSI: ASAM OSI®
20+
:GLO_VAR_STA_ASAM_OpenSCENARIO: ASAM OpenSCENARIO
21+
:GLO_VAR_STA_ASAM_OpenXOntology: ASAM OpenXOntology
22+
:GLO_VAR_STA_BSI_PAS_1883: BSI PAS 1883
23+
:revnumber: --localbuild--
24+
:revdate: {docdate}
25+
:bibtex-file: ./content/general_docs/bibliography.bib
26+
// Replace PLACEHOLDER with the name of your standard, e.g. OpenDRIVE
27+
:THIS_STANDARD: {GLO_VAR_STA_ASAM_OSI}
28+
:THIS_STANDARD_TITLE: {GLO_VAR_STA_ASAM_OSI}
29+
:asam-terminology: https://code.asam.net/common/asam-terminology/-/raw/main/terms_and_definitions_opendrive.adoc
30+
:imagesdir: {root-path}_static/images
31+
:include-only-once: true
32+
:topicdir: topics
33+
:reusedir: reuse
34+
:toclevels: 3
35+
:xrefstyle: full
36+
// :images_osi-sensor-model-packaging: ../../osi-sensor-model-packaging/doc/images
37+
:doc_open_simulation_interface: open-simulation-interface/doc/
38+
:doc_osi-sensor-model-packaging: osi-sensor-model-packaging/doc/
39+
:images_open_simulation_interface: ../../open-simulation-interface/doc/images
40+
// Since a document spanning multiple repos is rendered here, the pathing regarding images is a bit involved.
41+
// We create a variable for every repo that is included. It point to the repo in question.
42+
// If the subrepo is rendered seperatly, then the variable is set to just "./images" with ifdef.
43+
// Please note that this variable has to used in all image includes. Includes here have to use "image::./images..."
44+
// :images_osi_sensor_model_packaging: ./osi-sensor-model-packaging/doc/images // example
45+
:imagesoutdir: ./images/generated_images
46+
:page-feedbackurl: https://github.com/OpenSimulationInterface/osi-documentation/issues/new
47+
48+
endif::[]
49+
50+
ifndef::use-antora-rules[]
51+
include::{asciidoc-resources}/preamble.adoc[]
52+
endif::[]
53+
54+
ifdef::env-gitlab[]
55+
:relfilesuffix: .adoc
56+
endif::[]

0 commit comments

Comments
 (0)