diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 5ac1899..25cf88c 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -18,4 +18,4 @@ Add @mentions of the person or team responsible for reviewing proposed changes. - [ ] I have performed a self-review of my own code/documentation. - [ ] My documentation changes are related to another repository in the organization. Here is the link to the issue/repo. - [ ] My changes generate no new warnings during the documentation generation. -- [ ] The existing travis ci which pushes the documentation to gh-pages passes with my changes. \ No newline at end of file +- [ ] The Antora pipeline which pushes the documentation to gh-pages on the downstream repository passes with my changes. \ No newline at end of file diff --git a/.github/workflows/asciidoc-build.yml b/.github/workflows/asciidoc-build.yml deleted file mode 100644 index 568f9a8..0000000 --- a/.github/workflows/asciidoc-build.yml +++ /dev/null @@ -1,90 +0,0 @@ -name: AsciiDoc Documentation Build - -on: - create: # new branches or tags - release: # new releases - pull_request: - branches: [ 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: - asciidoctor-build: - name: Run Asciidoctor on Documentation - - runs-on: ubuntu-22.04 - - steps: - # Checkout osi documentation - - name: Checkout osi-documentation - uses: actions/checkout@v2 - with: - submodules: true - fetch-depth: 0 - - # Checkout all other OSI repositories with branch "migration" and nested into osi-documentation - - name: Checkout open-simulation-interface - uses: actions/checkout@v2 - with: - repository: OpenSimulationInterface/open-simulation-interface - path: content/open-simulation-interface - fetch-depth: 0 - - - - name: Checkout OSI Sensor Model Packaging - uses: actions/checkout@v2 - with: - repository: OpenSimulationInterface/osi-sensor-model-packaging - path: content/osi-sensor-model-packaging - - - name: Checkout proto2cpp - uses: actions/checkout@v2 - with: - repository: OpenSimulationInterface/proto2cpp - path: proto2cpp - - # Versioning - - name: Get versioning - id: get_version - 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:" 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:/' 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 content/index.adoc -o open-simulation-interface_V${{ steps.get_version.outputs.VERSION }}.html" - - # Upload artifact. - - name: Upload HTML Artifact - uses: actions/upload-artifact@v2 - if: ${{ github.event_name == 'pull_request' }} - with: - name: HTML document - path: open-simulation-interface_V${{ steps.get_version.outputs.VERSION }}.html - if-no-files-found: error - - # Publish the artifact when pipeline runs on master - - name: rename file for deploy to gh-page - if: ${{ github.ref == 'refs/heads/master' }} - run: | - mkdir html/ - cp open-simulation-interface_V${{ steps.get_version.outputs.VERSION }}.html html/index.html - - - name: deploy to gh-pages if push to master branch - if: ${{ github.ref == 'refs/heads/master' }} - uses: peaceiris/actions-gh-pages@v3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./html diff --git a/README.adoc b/README.adoc index 459100a..6e0d7f1 100644 --- a/README.adoc +++ b/README.adoc @@ -1,38 +1,27 @@ = OSI Documentation -This repo hosts the AsciiDoc-based part of the documentation. +This repo contains most of the general AsciiDoc-based part of the documentation. It contains generals parts of the content and a CI-pipeline that renders the document with Antora. -// TODO: Update if Asciidoctor is completely dropped! +NOTE: The actual hosting has been moved to the generator repository (see link below). == ASAM OSI (R) official documentation See the documentation https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/specification/index.html[here]. -== Build pipeline -// === Asciidoctor pipeline - -// The Asciidoctor pipline is no longer active, see Antora 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 +== Antora build 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] 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. +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. +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. @@ -41,7 +30,7 @@ The instruction should work on Windows, Linux, and MacOS. + TIP: Official installation can be found https://docs.docker.com/get-docker/[here]. -. Clone this repository with submodules. +. Clone this repository with submodules. + [source, shell] ---- @@ -63,17 +52,17 @@ git clone https://github.com/OpenSimulationInterface/osi-sensor-model-packaging. [source, yaml] ---- version: "2" - - services: + + services: asciidoctor: image: asciidoctor/docker-asciidoctor:1 - volumes: + 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 ---- -. Run +. Run + [source, shell] ---- diff --git a/content/general_docs/osi_repos.adoc b/content/general_docs/osi_repos.adoc index dfbeebd..242f0b8 100644 --- a/content/general_docs/osi_repos.adoc +++ b/content/general_docs/osi_repos.adoc @@ -11,10 +11,14 @@ OSI and its supporting tools are developed publicly on GitHub. The source code and documentation for OSI and OSI-related tools are spread over several repositories: https://github.com/OpenSimulationInterface/open-simulation-interface[open-simulation-interface]:: -Main repository containing the interface description based on Google's Protocol Buffers, including helper scripts and test scripts. Hosts the .proto files as well as the https://opensimulationinterface.github.io/open-simulation-interface/[Doxygen reference documentation]. +Main repository containing the interface description based on Google's Protocol Buffers, including helper scripts and test scripts. +Hosts the .proto files. -https://github.com/OpenSimulationInterface/osi-documentation[osi-documentation]:: Source for the OSI user guide sources and hosts the https://opensimulationinterface.github.io/osi-documentation/[{THIS_STANDARD} user guide]. +https://github.com/OpenSimulationInterface/osi-documentation[osi-documentation]:: Source for the AsciiDoc files used to compile the general chapters of the OSI documentation. https://github.com/OpenSimulationInterface/osi-sensor-model-packaging[osi-sensor-model-packaging]:: Packaging specification for OSI models used in FMI 2.0 cite:[fmi2.0] simulation environments, including examples. -https://github.com/OpenSimulationInterface/proto2cpp[proto2cpp]:: Doxygen filter for creating the reference documentation from OSI .proto files. \ No newline at end of file +https://github.com/OpenSimulationInterface/proto2cpp[proto2cpp]:: Doxygen filter for creating the reference documentation from OSI .proto files. + +https://github.com/OpenSimulationInterface/osi-antora-generator[osi-antora-generator]:: Contains the Antora generator and the relevant pipeline. +This repository is responsible for both building and hosting the https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/specification/index.html/[{THIS_STANDARD} Specification^] as well as the https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/gen/index.html[{THIS_STANDARD} Reference Documentation^]. \ No newline at end of file