ASAM OSI - Antora generator

Important

This repository contains the generator and general setup for Antora in context of ASAM OSI. It does not contain the content itself!

The pipeline of this repository is responsible for creating the combined and versioned Antora output for ASAM OSI. It also pushes it to the respective GitHub pages for hosting.

Hosted version available at: ASAM OSI (link)

Building locally

1. Precondition: have docker and docker-compose installed. Have access to the ASAM GitLab Antora extensions repository.

   Tip	Official installation can be found here.

2. Clone this repository with submodules.

   git clone --recurse-submodules https://github.com/OpenSimulationInterface/osi-antora-generator.git

3. Recommended: To use local content instead of pulling from remote every time, check out all content repositories (osi-documentation, open-simulation-interface, and osi-sensor-model-packaging) into this repository’s root (e.g. "./osi-documentation"). You may also choose to only check out a selection of these repositories.

   cd osi-antora-generator
   git clone --recurse-submodules https://github.com/OpenSimulationInterface/osi-documentation.git
   git clone --recurse-submodules https://github.com/OpenSimulationInterface/open-simulation-interface.git
   git clone --recurse-submodules https://github.com/OpenSimulationInterface/osi-sensor-model-packaging.git

4. Copy the 'site.yml' as 'site_local.yml'

   1. Recommended: For local content, switch the url of all local repositories from remote to local (comment out/in respective line with url:)

   2. Optional: To build a specific branch, replace the related entry under branches: or add it to the array. Alternatively, switch to 'HEAD' by commenting out/in the respective lines with branches: For more information on how the 'site.yml' works, see the official Antora documentation.

5. To run Antora, run docker-compose:

   docker-compose -f docker-compose-local.yml

   1. Alternatively, you can run the build.py script in the folder scripts, which will build the result and automatically open it in chrome afterwards.

      Note	Either way, Antora will create and build the result into a 'site/' folder.

Important

This setup runs doxygen builds by default. Note that these can take more than five minutes per version! If you are iterating over small or multiple text changes, consider deactivating the doxygen build steps by commenting out the line doxygen: true in your site_local.yml. Alternatively, limit your build to only your current content (i.e. comment out the tags and only add HEAD as branch).

Tip

If you are using VSCode, there is currently no correctly working support for source control of nested git projects. However, there exists a workaround: Check out the repositories as described above but do not add them to your workspace. If they are already in your workspace, remove them from there. Next, add the innermost repository (the content repositories) to your workspace first. Then, continue outwards until you added the uppermost repository (the generator).

Local PDF builder

Important

This only works for a local setup!

Click for local PDF builder setup instructions

To build Antora into PDF (which only works locally right now), you have to change a few settings.

First, enter your docker-compose-local.yml file, comment out the line below Default generator setup, then comment in the line below BE AWARE that this currently does not support the use of © or ®! You must alter the respective lines in osi-documentation/.antora/antora.yml. Make sure not to check these changes in!.

Next, open the 'antora.yml' file in your 'osi-documentation/.antora' folder and change the following lines from

THIS_STANDARD: ASAM OSI<sup>®</sup> # Normal attribute
THIS_STANDARD_TITLE: 'ASAM OSI^®^' # Normal attribute
# THIS_STANDARD: ASAM OSI # PDF version attribute
# THIS_STANDARD_TITLE: 'ASAM OSI' # PDF version attribute

to

# THIS_STANDARD: ASAM OSI<sup>®</sup> # Normal attribute
# THIS_STANDARD_TITLE: 'ASAM OSI^®^' # Normal attribute
THIS_STANDARD: ASAM OSI # PDF version attribute
THIS_STANDARD_TITLE: 'ASAM OSI' # PDF version attribute