diff --git a/.gitignore b/.gitignore
index 78aba4bb88ae15cc77fd1bb1b454f37c145e3839..64adf30139f5da14a6e83494de50159c10b76665 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,3 +6,4 @@
.idea/
.gradle/
build/
+public/
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 8551b9eb54f6582ca867acb77486de5bc3d17aa7..2bd5703df929c32cdef66c41e99cb66092c9adca 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -1,10 +1,13 @@
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
diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..3b162ddae3e87812e517c2c20ce639186cf05946
--- /dev/null
+++ b/README.md
@@ -0,0 +1,7 @@
+# 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).
diff --git a/pages/.gitattributes b/pages/.gitattributes
index 6b5d9827cd5416e9e2568615d135b563f76cdbc5..1397af0c29996b68da5f01a8a92d8f4aca20427a 100644
--- a/pages/.gitattributes
+++ b/pages/.gitattributes
@@ -1 +1,2 @@
-_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
diff --git a/pages/.gitignore b/pages/.gitignore
index 87174b686c0670d3fb6a66535729af2a8a249d72..a95071c4b0fd05bccf528339a15b2e93458bc694 100644
--- a/pages/.gitignore
+++ b/pages/.gitignore
@@ -1 +1 @@
-/public/
+/docs/ragdoc/
diff --git a/pages/Makefile b/pages/Makefile
deleted file mode 100644
index 7878ee5305af7d6c04860113aa9ef008991d07af..0000000000000000000000000000000000000000
--- a/pages/Makefile
+++ /dev/null
@@ -1,20 +0,0 @@
-# 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)
diff --git a/pages/_static/moving-robot.mp4 b/pages/_static/moving-robot.mp4
deleted file mode 100644
index 05f00803bcceb88eb08a7b4dd44f297e359c8b32..0000000000000000000000000000000000000000
Binary files a/pages/_static/moving-robot.mp4 and /dev/null differ
diff --git a/pages/conf.py b/pages/conf.py
deleted file mode 100644
index bdd91e4f410636b477239f5ff4285eced4516914..0000000000000000000000000000000000000000
--- a/pages/conf.py
+++ /dev/null
@@ -1,66 +0,0 @@
-# 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'
diff --git a/pages/custom_theme/footer.html b/pages/custom_theme/footer.html
new file mode 100644
index 0000000000000000000000000000000000000000..2d6c164695b3a1ed19711d3497caf142a8416ebb
--- /dev/null
+++ b/pages/custom_theme/footer.html
@@ -0,0 +1,11 @@
+{% 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 %}
diff --git a/pages/adding.md b/pages/docs/adding.md
similarity index 100%
rename from pages/adding.md
rename to pages/docs/adding.md
diff --git a/pages/extending.md b/pages/docs/extending.md
similarity index 55%
rename from pages/extending.md
rename to pages/docs/extending.md
index baa6c5380f5dad2c3e351a3027c6c9a287e96f6d..246b7a7527016298320fb89220988ccd6399fe49 100644
--- a/pages/extending.md
+++ b/pages/docs/extending.md
@@ -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):
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
+ - 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
+ - Add a new static boolean flag `usesABC` to indicate whether the protocol is used
- In `backend/Generation`:
- - 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 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 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 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`:
- - 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-pair for `usesABC` (and handler, 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`:
+
- 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)
+
diff --git a/pages/docs/img/moving-robot.mp4 b/pages/docs/img/moving-robot.mp4
new file mode 100644
index 0000000000000000000000000000000000000000..40da2c6367777d89f1b0193b19312363f0ef0db1
--- /dev/null
+++ b/pages/docs/img/moving-robot.mp4
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:814b592f202dd72ae2cdb7b0841faefbc963d7847d9f568aca75547c647ee1e3
+size 1867731
diff --git a/pages/_static/mpm4cps-slides.pdf b/pages/docs/img/mpm4cps-slides.pdf
similarity index 100%
rename from pages/_static/mpm4cps-slides.pdf
rename to pages/docs/img/mpm4cps-slides.pdf
diff --git a/pages/_static/poster-presentation.mp4 b/pages/docs/img/poster-presentation.mp4
similarity index 100%
rename from pages/_static/poster-presentation.mp4
rename to pages/docs/img/poster-presentation.mp4
diff --git a/pages/_static/poster.pdf b/pages/docs/img/poster.pdf
similarity index 100%
rename from pages/_static/poster.pdf
rename to pages/docs/img/poster.pdf
diff --git a/pages/images/robo3d.png b/pages/docs/img/robo3d.png
similarity index 100%
rename from pages/images/robo3d.png
rename to pages/docs/img/robo3d.png
diff --git a/pages/images/ros2rag-process.png b/pages/docs/img/ros2rag-process.png
similarity index 100%
rename from pages/images/ros2rag-process.png
rename to pages/docs/img/ros2rag-process.png
diff --git a/pages/docs/index.md b/pages/docs/index.md
new file mode 100644
index 0000000000000000000000000000000000000000..d345eec5f7a9f7a688dbf28ced0f95e7dbd74566
--- /dev/null
+++ b/pages/docs/index.md
@@ -0,0 +1,3 @@
+# 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/).
diff --git a/pages/inner-workings.md b/pages/docs/inner-workings.md
similarity index 93%
rename from pages/inner-workings.md
rename to pages/docs/inner-workings.md
index 9a244b9e72debabc3cdb138c7654fb66ce217f53..6d8b41e13847f2ae337f08c65068cbef6085e065 100644
--- a/pages/inner-workings.md
+++ b/pages/docs/inner-workings.md
@@ -1,6 +1,8 @@
# Inner workings of `RagConnect`
-
+Please see [API documentation](ragdoc/index.html) for more details.
+
+
`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`.
diff --git a/pages/use_cases.md b/pages/docs/use_cases.md
similarity index 74%
rename from pages/use_cases.md
rename to pages/docs/use_cases.md
index c479b65fdf40260ec8759617fa9f20e7529302fe..b815b7a5f6fab004f4573e29054858a10fd5d7db 100644
--- a/pages/use_cases.md
+++ b/pages/docs/use_cases.md
@@ -1,17 +1,17 @@
# 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.
-
+
-[📽 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.
diff --git a/pages/using.md b/pages/docs/using.md
similarity index 100%
rename from pages/using.md
rename to pages/docs/using.md
diff --git a/pages/index.rst b/pages/index.rst
deleted file mode 100644
index 2da98fa853da557649b89085755852cac20cef7c..0000000000000000000000000000000000000000
--- a/pages/index.rst
+++ /dev/null
@@ -1,27 +0,0 @@
-.. RagConnect documentation master file, created by
- sphinx-quickstart on Fri Aug 28 10:16:26 2020.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
-
-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 `Relation Reference Attribute Grammars <https://doi.org/10.1016/j.cola.2019.100940>`_ built with `JastAdd <http://jastadd.org/>`_.
-
-.. toctree::
- :maxdepth: 2
- :caption: Contents:
-
- use_cases.md
- adding.md
- inner-workings.md
- using.md
- extending.md
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`
diff --git a/pages/make.bat b/pages/make.bat
deleted file mode 100644
index c6abfba46443f5335943b13912c8d7b6d62ae644..0000000000000000000000000000000000000000
--- a/pages/make.bat
+++ /dev/null
@@ -1,35 +0,0 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
- set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=.
-set BUILDDIR=public
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
- echo.
- echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
- echo.installed, then set the SPHINXBUILD environment variable to point
- echo.to the full path of the 'sphinx-build' executable. Alternatively you
- echo.may add the Sphinx directory to PATH.
- echo.
- echo.If you don't have Sphinx installed, grab it from
- echo.http://sphinx-doc.org/
- exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd
diff --git a/pages/material/mpm4cps-slides.pdf b/pages/material/mpm4cps-slides.pdf
deleted file mode 100644
index 266f4e68e8806a398189cee8939ec393bf7f4ef4..0000000000000000000000000000000000000000
Binary files a/pages/material/mpm4cps-slides.pdf and /dev/null differ
diff --git a/pages/mkdocs.yml b/pages/mkdocs.yml
new file mode 100644
index 0000000000000000000000000000000000000000..fe8acd8466cf0b201ee3e0532199184840cb6611
--- /dev/null
+++ b/pages/mkdocs.yml
@@ -0,0 +1,21 @@
+site_name: RagConnect Documentation
+nav:
+ - use_cases.md
+ - adding.md
+ - inner-workings.md
+ - using.md
+ - extending.md
+ - API documentation: ragdoc/index.html
+theme:
+ name: readthedocs
+ custom_dir: custom_theme/
+plugins:
+ - search
+ - git-revision-date-localized:
+ type: datetime
+ timezone: Europe/Berlin
+ locale: en
+ fallback_to_build_date: True
+ - macros
+repo_url: https://git-st.inf.tu-dresden.de/jastadd/ragconnect
+site_dir: ../public