README.adoc

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 with Asciidoctor and deploys it to the gh-pages of this repo.

ASAM OSI ® official documentation

See the documentation here.

Build pipeline

Asciidoctor pipeline

The pipeline collects the documentation from both open-simulation-interface and 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 index.adoc.

Antora pipeline

Note	This pipeline runs on https://github.com/OpenSimulationInterface/osi-antora-generator.

How To build and change documentation locally

Important

These instructions relate ONLY to the Asciidoctor build. For Antora, check the 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.

1. Precondition: have docker and docker-compose installed.

   Tip	Official installation can be found here.

2. Clone this repository with submodules.

   git clone https://github.com/OpenSimulationInterface/osi-documentation.git
   git submodule update --init

3. Clone OSI and OSMP with submodules into the osi-documentation folder

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

4. Check file docker-compose.yml with the following content:

     version: "2"
   
     services:
     asciidoctor:
         image: asciidoctor/docker-asciidoctor:1
         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

5. Run

   docker-compose run asciidoctor

6. Result: Document is build as open-simulation-interface_localbuild.html in the folder osi-documentation.