How opensimulationinterface/osi-documentation works
Project type and purpose
• This is a documentation-focused repository. It uses AsciiDoc source files, an Antora site generator, and Docker/Asciidoctor for local builds. Its main goal is to assemble, render, and publish the ASAM OSI specification documentation by combining local content and external submodules.
File structure
• Top-level directories:
• .antora – Antora playbook and module skeleton (antora.yml, modules/specification).
• content – AsciiDoc chapters, appendices, release notes, contributing guides.
• local_build_tools – helper scripts and Docker Compose snippets for local Asciidoctor builds.
• .github/workflows – CI pipelines for Antora site builds and legacy Asciidoc builds.
• docker-compose.yml – definition of a containerized Asciidoctor service.
• .gitmodules – references two submodule repositories (open-simulation-interface, osi-sensor-model-packaging).
README for additional insights
• Explains two build pipelines:
• Asciidoctor (local or legacy CI) – containerized via Docker Compose, renders index.adoc to HTML.
• Antora (current CI) – orchestrated in a separate repo (osi-antora-generator), pulls this repo plus submodules, builds the full site, and publishes to GitHub Pages.
a. Main components
1. Source Content:
– Local AsciiDoc files under content/ and .antora/modules.
– External modules via Git submodules (OSI spec, sensor-model content).
2. Configuration:
– antora.yml (site layout, module mapping).
– Docker Compose YAML and local_build_tools scripts.
– GitHub Actions workflow YAMLs.
3. Build Engines:
– Antora site generator (CI pipeline).
– Asciidoctor container (local/legacy pipeline).
4. CI/CD Platform:
– GitHub Actions (triggers on push to main).
5. Output & Deployment:
– Static HTML site.
– Hosted on GitHub Pages via osi-antora-generator.
b. Relationships & data flow
– Content repositories (this repo + submodules) feed into Antora Playbook.
– antora.yml and module descriptors tell Antora how to assemble pages.
– GitHub Actions invokes Antora, producing HTML.
– Docker Compose or local_build_tools scripts invoke Asciidoctor for local preview builds.
– Final site artifacts are deployed to GitHub Pages.
c. Architectural patterns & principles
– Modular documentation (Antora modules pattern).
– Pipeline-as-code (GitHub Actions YAML).
– Containerized local builds for reproducibility.
– External content integration via Git submodules.
d. Key technologies & frameworks
– AsciiDoc / Antora / Asciidoctor
– Docker & Docker Compose
– GitHub Actions / Git submodules
Key details
– Labels for all repos, modules, and workflows.
– The dual-pipeline nature (CI vs local).
– The role of antora.yml in orchestrating module assembly.
– Deployment path to GitHub Pages.