Commit bee40252 authored by René Schöne's avatar René Schöne
Browse files

Switch from sphinx to mkdocs

parent 36f7affd
Pipeline #8802 passed with stages
in 9 minutes and 55 seconds
...@@ -6,3 +6,4 @@ ...@@ -6,3 +6,4 @@
.idea/ .idea/
.gradle/ .gradle/
build/ build/
public/
...@@ -33,6 +33,8 @@ test: ...@@ -33,6 +33,8 @@ test:
services: services:
- name: "eclipse-mosquitto:1.6.9" - name: "eclipse-mosquitto:1.6.9"
alias: "mqtt" alias: "mqtt"
needs:
- build
script: script:
- ./gradlew --console=plain --no-daemon allTests - ./gradlew --console=plain --no-daemon allTests
artifacts: artifacts:
...@@ -44,6 +46,8 @@ test: ...@@ -44,6 +46,8 @@ test:
publish: publish:
image: openjdk:11 image: openjdk:11
stage: publish stage: publish
needs:
- test
script: script:
- "./gradlew publish" - "./gradlew publish"
only: only:
...@@ -54,7 +58,7 @@ ragdoc_build: ...@@ -54,7 +58,7 @@ ragdoc_build:
name: "git-st.inf.tu-dresden.de:4567/jastadd/ragdoc-builder" name: "git-st.inf.tu-dresden.de:4567/jastadd/ragdoc-builder"
entrypoint: [""] entrypoint: [""]
stage: ragdoc_build stage: ragdoc_build
dependencies: needs:
- build - build
script: script:
- JAVA_FILES=$(find ragconnect.base/src/ -name '*.java') - JAVA_FILES=$(find ragconnect.base/src/ -name '*.java')
...@@ -68,26 +72,31 @@ ragdoc_view: ...@@ -68,26 +72,31 @@ ragdoc_view:
name: "git-st.inf.tu-dresden.de:4567/jastadd/ragdoc-view:relations" name: "git-st.inf.tu-dresden.de:4567/jastadd/ragdoc-view:relations"
entrypoint: [""] entrypoint: [""]
stage: ragdoc_view stage: ragdoc_view
dependencies: needs:
- ragdoc_build - ragdoc_build
script: script:
- DATA_DIR=$(pwd -P)/data - DATA_DIR=$(pwd -P)/data
- mkdir -p pages/_static/ragdoc - mkdir -p pages/docs/ragdoc
- OUTPUT_DIR=$(pwd -P)/pages/_static/ragdoc - OUTPUT_DIR=$(pwd -P)/pages/docs/ragdoc
- cd /ragdoc-view - cd /ragdoc-view/src/ && rm -rf data && ln -s $DATA_DIR
- ( cd src/ && rm -rf data && ln -s $DATA_DIR )
- /ragdoc-view/build-view.sh --output-path=$OUTPUT_DIR - /ragdoc-view/build-view.sh --output-path=$OUTPUT_DIR
- ls -lah $OUTPUT_DIR
artifacts: artifacts:
paths: paths:
- "pages/_static/ragdoc" - "pages/docs/ragdoc"
pages: pages:
image: python:3.7-alpine image: python:3.8-buster
stage: publish stage: publish
needs:
- ragdoc_view
- test
before_script:
- pip install -U mkdocs mkdocs-macros-plugin mkdocs-git-revision-date-plugin
script: script:
- pip install -U sphinx sphinx-rtd-theme recommonmark sphinxemoji sphinx-markdown-tables - cd pages && mkdocs build
- sphinx-build -b html pages/ public only:
- dev
- master
artifacts: artifacts:
paths: paths:
- public - public
# 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).
_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
# 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)
# 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'
{% 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.revision_date %}
<small><br><i>Last updated {{ page.meta.revision_date.strftime('%B %d, %Y at %H:%M') }}</i></small>
{% endif %}
</p>
{% endblock %}
...@@ -3,24 +3,30 @@ ...@@ -3,24 +3,30 @@
To add a new communication protocol, the following locations have to be changed (replace `ABC` and `abc` with the name of the protocol): 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`: Within `ragconnect.base/src/main/resources`:
{% raw %}
- Add a new handler `ABCHandler`, if appropriate, similar to the existing handlers - 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 - 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`. - 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`: Within `ragconnect.base/src/main/jastadd`:
- In `backend/Configuration`: - In `backend/Configuration`:
- Add a new static boolean flag `usesABC` to indicate whether the protocol is used - Add a new static boolean flag `usesABC` to indicate whether the protocol is used
- In `backend/Generation`: - In `backend/Generation`:
- Add new attributes for type `MRagConnect` for handler attribute and handler field, if needed - Add new attributes for type `MRagConnect` for handler attribute and handler field, if needed
- Add attributes for newly introduced references in changed mustache templates, if any - Add attributes for newly introduced references in changed mustache templates, if any
- Add a newly constructed handler within the definition of `RagConnect.toMustache` with the needed fields (class name, construction snippet, handler attribute, handler field, the boolean flag you just added to Configuration) - Add a newly constructed handler within the definition of `RagConnect.toMustache` with the needed fields (class name, construction snippet, handler attribute, handler field, the boolean flag you just added to Configuration)
- In `backend/MustacheNodesToYAML`: - In `backend/MustacheNodesToYAML`:
- Add key-value-pair for `usesABC` (and handler, if any) - Add key-value-pair for `usesABC` (and handler, if any)
- Add key-value-pairs for newly introduced referemces in changed mustache templates, if any - 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`: In `ragconnect.base/src/main/java/org/jastadd/ragconnect/compiler/Compiler.java`:
- Add a new choice for `--protocols` similar to the existing ones - Add a new choice for `--protocols` similar to the existing ones
- Set the flag `usesABC` if the choice is given. - 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` - 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) 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)
# 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/).
# Inner workings of `RagConnect` # Inner workings of `RagConnect`
Please see [API documentation](_static/ragdoc/index.html) for more details. Please see [API documentation](ragdoc/index.html) for more details.
![ros2rag-process](images/ros2rag-process.png) ![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`. `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`. It further uses a dedicated parser for `.connect` files containing endpoint-, mapping-, and dependency-definitions. This results in an ASTNode of type `RagConnect`.
......
# Use cases with `RagConnect` # 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. 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 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. The usage is dockerized, so starting the application only involves the commands listed below.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment