From a94448a5cb556a172f4e5c5428feb44aaa6507d0 Mon Sep 17 00:00:00 2001 From: PhRosenberger Date: Wed, 19 Jan 2022 10:30:44 +0100 Subject: [PATCH 1/2] Adding Build instructions for Docker on Windows --- README.rst | 19 ++++++++++++++++++- docker-compose.yml | 9 +++++++++ 2 files changed, 27 insertions(+), 1 deletion(-) create mode 100644 docker-compose.yml diff --git a/README.rst b/README.rst index f77334c5..a43030fd 100644 --- a/README.rst +++ b/README.rst @@ -17,7 +17,24 @@ Pipeline is broken - `OSI Validation`_ |osi_sensor_model_packaging_build| - `OSI Model Packaging`_ - +How To build and change Documentation locally on Windows +-------------------------------------------------------- +- Install Docker Desktop +- Clone this repository with submodules +- Clone OSI and OSMP with submodules into this folder +- Check file ``docker-compose.yml`` with the following content: + +.. code-block:: yaml + + 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 .. _Open Simulation Interface: https://opensimulationinterface.github.io/osi-documentation/open-simulation-interface/README.html .. _OSI Validation: https://opensimulationinterface.github.io/osi-documentation/osi-validation/README.html diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 00000000..0af36db2 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,9 @@ +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 \ No newline at end of file From 1ea2b0db3d7252fef09bddeb824557f90bfc745e Mon Sep 17 00:00:00 2001 From: Stefan Cyliax Date: Fri, 21 Jan 2022 07:47:17 +0100 Subject: [PATCH 2/2] Rewrite build instructions (#49) also migrated the README to asciidoc as other documentation Signed-off-by: Stefan Cyliax --- README.adoc | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.rst | 54 ----------------------------------------- 2 files changed, 69 insertions(+), 54 deletions(-) create mode 100644 README.adoc delete mode 100644 README.rst diff --git a/README.adoc b/README.adoc new file mode 100644 index 00000000..958ac5b5 --- /dev/null +++ b/README.adoc @@ -0,0 +1,69 @@ += 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 and deploys it the the https://opensimulationinterface.github.io/osi-documentation/[gh-pages of this repo]. + +== ASAM OSI (R) official documentation + +See the documentation https://opensimulationinterface.github.io/osi-documentation/[here]. + + +== Build 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 asciidoc project the complete document structure is described in the mapping file https://github.com/OpenSimulationInterface/osi-documentation/blob/master/index.adoc[index.adoc]. + + +== How To build and change documentation locally + +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. + +The instruction should work on Windows, Linux and MacOS. + +. *Precondition*: have docker and docker-compose installed. ++ +TIP: Official installation can be found https://docs.docker.com/get-docker/[here]. + +. Clone this repository with submodules. ++ +[source, shell] +---- +git clone https://github.com/OpenSimulationInterface/osi-documentation.git +git submodule update --init +---- + +. Clone OSI and OSMP with submodules *into* the osi-documentation folder ++ +[source, shell] +---- +cd osi-documentation +git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git +git clone https://github.com/OpenSimulationInterface/osi-sensor-model-packaging.git +---- + +. Check file ``docker-compose.yml`` with the following content: ++ +[source, yaml] +---- + 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 +---- + +. Run ++ +[source, shell] +---- +docker-compose run asciidoctor +---- + +. *Result*: Document is build as `open-simulation-interface_localbuild.html` in the folder osi-documentation. \ No newline at end of file diff --git a/README.rst b/README.rst deleted file mode 100644 index a43030fd..00000000 --- a/README.rst +++ /dev/null @@ -1,54 +0,0 @@ -`OSI-Documentation `_ -====================================================================================== - -.. image:: https://github.com/OpenSimulationInterface/osi-documentation/actions/workflows/asciidoc-build.yml/badge.svg?branch=master - :target: https://github.com/OpenSimulationInterface/osi-documentation/actions/workflows/asciidoc-build.yml - -This is the main repository for the whole documentation of the osi-project. -The documentation is based on `asciidoc `_. See the documentation `here `_. - -Organization Build Overview ----------------------------- -|osi_build| - `Open Simulation Interface`_ - -Pipeline is broken - `OSI Validation`_ - -|osi_visualizer_build| - `OSI Visualizer`_ - -|osi_sensor_model_packaging_build| - `OSI Model Packaging`_ - -How To build and change Documentation locally on Windows --------------------------------------------------------- -- Install Docker Desktop -- Clone this repository with submodules -- Clone OSI and OSMP with submodules into this folder -- Check file ``docker-compose.yml`` with the following content: - -.. code-block:: yaml - - 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 - -.. _Open Simulation Interface: https://opensimulationinterface.github.io/osi-documentation/open-simulation-interface/README.html -.. _OSI Validation: https://opensimulationinterface.github.io/osi-documentation/osi-validation/README.html -.. _OSI Visualizer: https://opensimulationinterface.github.io/osi-documentation/osi-visualizer/README.html -.. _OSI Model Packaging: https://opensimulationinterface.github.io/osi-documentation/osi-sensor-model-packaging/README.html - -.. |osi_build| image:: https://github.com/OpenSimulationInterface/open-simulation-interface/actions/workflows/protobuf.yml/badge.svg - :target: https://github.com/OpenSimulationInterface/open-simulation-interface/actions/workflows/protobuf.yml - -.. |osi_validation_build| image:: .. - :target: .. - -.. |osi_visualizer_build| image:: https://github.com/OpenSimulationInterface/osi-visualizer/actions/workflows/ci-build.yml/badge.svg - :target: https://github.com/OpenSimulationInterface/osi-visualizer/actions/workflows/ci-build.yml - -.. |osi_sensor_model_packaging_build| image:: https://github.com/OpenSimulationInterface/osi-sensor-model-packaging/actions/workflows/protobuf.yml/badge.svg - :target: https://github.com/OpenSimulationInterface/osi-sensor-model-packaging/actions/workflows/protobuf.yml