Merge branch '16-repo-documentation' into 'dev'

Resolve "Repo documentation"

See merge request !1

.gitignore

@@ -6,3 +6,4 @@
 .idea/
 .gradle/
 build/
+public/

.gitlab-ci.yml

 variables:
   GIT_SUBMODULE_STRATEGY: recursive
+  GIT_DEPTH: 1000
 
 stages:
-- build
-- test
-- publish
+  - build
+  - test
+  - ragdoc_build
+  - ragdoc_view
+  - publish
 
 before_script:
   - export GRADLE_USER_HOME=`pwd`/.gradle
@@ -22,6 +25,7 @@ build:
   artifacts:
     paths:
       - "ragconnect.base/build/libs/ragconnect-*.jar"
+      - "ragconnect.base/src/gen"
     expire_in: 1 week
 
 test:
@@ -30,12 +34,10 @@ test:
   services:
     - name: "eclipse-mosquitto:1.6.9"
       alias: "mqtt"
+  needs:
+    - build
   script:
     - ./gradlew --console=plain --no-daemon allTests
-    - ls -lh
-    - ls -lh ragconnect.tests
-    - ls -lh ragconnect.tests/build/test-results/
-    - ls -lh ragconnect.tests/build/test-results/allTests
   artifacts:
     when: always
     reports:
@@ -45,19 +47,57 @@ test:
 publish:
   image: openjdk:11
   stage: publish
+  needs:
+    - test
   script:
     - "./gradlew publish"
   only:
     - master
 
+ragdoc_build:
+  image:
+    name: "git-st.inf.tu-dresden.de:4567/jastadd/ragdoc-builder"
+    entrypoint: [""]
+  stage: ragdoc_build
+  needs:
+    - build
+  script:
+    - JAVA_FILES=$(find ragconnect.base/src/ -name '*.java')
+    - /ragdoc-builder/start-builder.sh -excludeGenerated -d data/ $JAVA_FILES
+  artifacts:
+    paths:
+      - "data/"
+
+ragdoc_view:
+  image:
+    name: "git-st.inf.tu-dresden.de:4567/jastadd/ragdoc-view:relations"
+    entrypoint: [""]
+  stage: ragdoc_view
+  needs:
+    - ragdoc_build
+  script:
+    - DATA_DIR=$(pwd -P)/data
+    - mkdir -p pages/docs/ragdoc
+    - OUTPUT_DIR=$(pwd -P)/pages/docs/ragdoc
+    - cd /ragdoc-view/src/ && rm -rf data && ln -s $DATA_DIR
+    - /ragdoc-view/build-view.sh --output-path=$OUTPUT_DIR
+  artifacts:
+    paths:
+      - "pages/docs/ragdoc"
+
 pages:
-  image: python:3.7-alpine
+  image: python:3.8-buster
   stage: publish
+  needs:
+    - ragdoc_view
+    - test
+  before_script:
+    - pip install -U mkdocs mkdocs-macros-plugin mkdocs-git-revision-date-localized-plugin
   script:
-  - pip install -U sphinx sphinx-rtd-theme recommonmark sphinxemoji sphinx-markdown-tables
-  - sphinx-build -b html pages/ public
+    - cd pages && mkdocs build
+  only:
+    - dev
+    - master
   artifacts:
     paths:
     - public
-  only:
-  - master

README.md

+# RagConnect
+
+[RagConnect](https://git-st.inf.tu-dresden.de/jastadd/ragconnect) is a preprocessor to enable easy connection to/from models based on [Reference Attribute Grammars](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.108.8792&rep=rep1&type=pdf) and [Relational Reference Attribute Grammars](https://doi.org/10.1016/j.cola.2019.100940) built with [JastAdd](http://jastadd.org/).
+
+Documentation can be found at <http://connect.relational-rags.eu> including an API documentation.
+
+The most recent version is listed at the [package registry](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/packages).

pages/.gitattributes

-_static/poster-presentation.mp4 filter=lfs diff=lfs merge=lfs -text
+docs/img/poster-presentation.mp4 filter=lfs diff=lfs merge=lfs -text
+docs/img/moving-robot.mp4 filter=lfs diff=lfs merge=lfs -text

pages/.gitignore

-/public/
+/docs/ragdoc/

pages/Makefile

-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = public
-
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

pages/conf.py

-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-import sphinx_rtd_theme
-
-
-# -- Project information -----------------------------------------------------
-
-project = 'RagConnect'
-copyright = '2021, René Schöne, Johannes Mey'
-author = 'René Schöne, Johannes Mey'
-
-# The full version, including alpha/beta/rc tags
-ragconnectVersionFileName = '../ragconnect.base/src/main/resources/ragConnectVersion.properties'
-with open(ragconnectVersionFileName) as ragconnectVersionFile:
-    versionFileContent = ragconnectVersionFile.read()
-release = version = versionFileContent[versionFileContent.rindex('version=') + 8:].strip()
-print('Version: ' + version)
-
-
-# -- General configuration ---------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = [
-    'sphinx_rtd_theme',
-    'recommonmark',
-    'sphinxemoji.sphinxemoji',
-    'sphinx_markdown_tables'
-]
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
-
-
-# -- Options for HTML output -------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = 'sphinx_rtd_theme'
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-sphinxemoji_style = 'twemoji'

pages/custom_theme/footer.html

+{% block footer %}
+<p>{% if config.copyright %}
+<small>{{ config.copyright }}<br></small>
+{% endif %}
+<hr>
+Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
+{% if page and page.meta and page.meta.git_revision_date_localized %}
+<small><br><i>Last updated {{ page.meta.git_revision_date_localized }}</i></small>
+{% endif %}
+</p>
+{% endblock %}

pages/extending.md → pages/docs/extending.md

@@ -3,11 +3,15 @@
 To add a new communication protocol, the following locations have to be changed (replace `ABC` and `abc` with the name of the protocol):
 
 Within `ragconnect.base/src/main/resources`:
+
+{% raw %}
 - Add a new handler `ABCHandler`, if appropriate, similar to the existing handlers
     - If further methods are needed for handler initialization, add a new template `abc.mustache` containing those procedures. Add `{{#usesABC}}{{> abc}}{{/usesABC}}` at the top of `ragconnect.mustache` to use this template
 - In `receiveDefinition.mustache` and `sendDefinition.mustache`: add a new case in the switch statement defining the logic to happen for both definitions. If the new protocol is close to a PUSH semantic, follow `mqtt`. If it is closer to PULL semantic, follow `rest`.
+{% endraw %}
 
 Within `ragconnect.base/src/main/jastadd`:
+
 - In `backend/Configuration`:
     - Add a new static boolean flag `usesABC` to indicate whether the protocol is used
 - In `backend/Generation`:
@@ -19,8 +23,10 @@ Within `ragconnect.base/src/main/jastadd`:
     - Add key-value-pairs for newly introduced referemces in changed mustache templates, if any
 
 In `ragconnect.base/src/main/java/org/jastadd/ragconnect/compiler/Compiler.java`:
+
 - Add a new choice for `--protocols` similar to the existing ones
 - Set the flag `usesABC` if the choice is given.
 - Add code to add the handler to the list `handlers` if the choice is given, i.e., if `ASTNode.usesABC`
 
 Furthermore, new test cases are appreciated. They can be added in the [ragconnect.rests repository](https://git-st.inf.tu-dresden.de/jastadd/ragconnect-tests)
+

pages/docs/index.md

+# RagConnect Documentation
+
+[RagConnect](https://git-st.inf.tu-dresden.de/jastadd/ragconnect) is a preprocessor to enable easy connection to/from models based on [Reference Attribute Grammars](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.108.8792&rep=rep1&type=pdf) and [Relational Reference Attribute Grammars](https://doi.org/10.1016/j.cola.2019.100940) built with [JastAdd](http://jastadd.org/).

pages/inner-workings.md → pages/docs/inner-workings.md

 # Inner workings of `RagConnect`
 
-![ros2rag-process](images/ros2rag-process.png)
+Please see [API documentation](ragdoc/index.html) for more details.
+
+![ros2rag-process](img/ros2rag-process.png)
 
 `RagConnect` uses the [relast-preprocessor](https://git-st.inf.tu-dresden.de/jastadd/relast-preprocessor) to parse `.relast` grammar files. This results in an ASTNode of type `Program`.
 It further uses a dedicated parser for `.connect` files containing endpoint-, mapping-, and dependency-definitions. This results in an ASTNode of type `RagConnect`.

pages/use_cases.md → pages/docs/use_cases.md

 # Use cases with `RagConnect`
 
-## 1⃣ MPM4CPS Paper - Codename 'Ros2Rag'
+## MPM4CPS Paper - Codename 'Ros2Rag'
 
-In the publication [*"Connecting conceptual models using Relational Reference Attribute Grammars"*](https://doi.org/10.1145/3417990.3421437), a use case involving a simulated robot arm and two different models conencted to it was shown.
+In the publication [*"Connecting conceptual models using Relational Reference Attribute Grammars"*](https://doi.org/10.1145/3417990.3421437), a use case involving a simulated robot arm and two different models connected to it was shown.
 One model was used to ensure a low speed of the robot when within a safety zone (purple boxes in the picture below), and the other model executes a workflow to control the robot.
 
-![Screenshot of Gazebo](images/robo3d.png)
+![Screenshot of Gazebo](img/robo3d.png)
 
-[📽 Recording of the simulated robot during the use case](_static/moving-robot.mp4)
+[📽 Recording of the simulated robot during the use case](img/moving-robot.mp4)
 
-This paper was presented on October, 16h during the [MPM4CPS workshop](https://msdl.uantwerpen.be/conferences/MPM4CPS/2020/) within the [MODELS 2020 conference](https://conf.researchr.org/home/models-2020). For more information, see the [presented slides](_static/mpm4cps-slides.pdf) or the [a recording of the session](https://youtu.be/Hgc1qFfmr44?t=1220).
+This paper was presented on October, 16h during the [MPM4CPS workshop](https://msdl.uantwerpen.be/conferences/MPM4CPS/2020/) within the [MODELS 2020 conference](https://conf.researchr.org/home/models-2020). For more information, see the [presented slides](img/mpm4cps-slides.pdf) or the [a recording of the session](https://youtu.be/Hgc1qFfmr44?t=1220).
 
-There is also a [poster](_static/poster.pdf) and a [pre-recorded presentation](_static/poster-presentation.mp4) of this poster.
+There is also a [poster](img/poster.pdf) and a [pre-recorded presentation](img/poster-presentation.mp4) of this poster.
 
 The repository with the used source code can be found at: <https://git-st.inf.tu-dresden.de/ceti/ros/mpm4cps2020>
 The usage is dockerized, so starting the application only involves the commands listed below.