Merge branch 'release-0.3.0' into 'master'

Testing incremental dependency tracking.

See merge request !5

.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
@@ -21,7 +24,8 @@ build:
     - ./gradlew --console=plain --no-daemon assemble jar
   artifacts:
     paths:
-      - "/builds/jastadd/ragconnect/ragconnect.base/build/libs/ragconnect-*.jar"
+      - "ragconnect.base/build/libs/ragconnect-*.jar"
+      - "ragconnect.base/src/gen"
     expire_in: 1 week
 
 test:
@@ -30,29 +34,70 @@ test:
   services:
     - name: "eclipse-mosquitto:1.6.9"
       alias: "mqtt"
+  needs:
+    - build
   script:
     - ./gradlew --console=plain --no-daemon allTests
   artifacts:
+    when: always
     reports:
-      junit: "/builds/jastadd/ragconnect/ragconnect.tests/build/test-results/test/TEST-*.xml"
+      junit: "ragconnect.tests/build/test-results/**/TEST-*.xml"
     expire_in: 1 week
 
 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

.gitmodules

 [submodule "relast-preprocessor"]
 	path = relast-preprocessor
 	url = ../relast-preprocessor.git
+  branch = jastadd-fix-inc-param-debug
 [submodule "ragconnect.base/src/main/jastadd/mustache"]
 	path = ragconnect.base/src/main/jastadd/mustache
 	url = ../mustache

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/
+__pycache__

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/docs/extending.md

+# Extending `RagConnect`
+
+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`:
+    - 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
+
+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, see [below](#writing-tests).
+
+## Writing Tests
+
+To add new tests, have a look at the module `ragconnect.tests`.
+It has three parts:
+1) In `src/test/01-input/*` are the [specifications](#specifications) that are going to be compiled (in principle using the steps described in [the guide to add RagConnect](adding)).
+2) In `src/test/java`, the jUnit 5 [test classes](#test-classes) are implemented. They mostly correspond 1-to-1 to a directory of the first part.
+3) In `build.gradle` the [instructions how to compile](#buildgradle) the specifications using the gradle plugin [PreprocessorPlugin][preprocessor-plugin] (`org.jastadd.preprocessor:testing`).
+
+### Specifications
+
+Every specification must have at least a `README.md` to describe the purpose of the test, a grammar `Test.relast`, and a RagConnect specification `Test.connect`.
+Usually an aspect file `Test.jadd` is included.
+
+### Test Classes
+
+Based on jUnit 5, the test classes testing some behaviour. If sending and/or receiving functionality is used, consider extending `AbstractMqttTest` in order to avoid duplicate code. In case of extending this class, please order the methods according to their lifecycle, i.e.:
+- createModel
+- setupReceiverAndConnect
+- communicateSendInitialValue
+- communicateOnlyUpdatedValue
+- closeConnections
+
+Within `AbstractMqttTest`, an `MqttHandler` named `publisher` is available to publish content.
+Some convenience methods are provided in `TestUtils`, e.g., the `DefaultMappings`, and `mqttUri` to prepend `"mqtt://"` and the correct host for the mqtt broker (`localhost` or a CI-specific host).
+All tests are required to run both locally, and within the CI.
+
+### build.gradle
+
+Use the [PreprocessorPlugin][preprocessor-plugin], the build process can be written concisely in three parts per task:
+
+```groovy
+task compileTreeAllowedTokens(type: RagConnectTest) {
+    ragconnect {
+        outputDir = file('src/test/02-after-ragconnect/treeAllowedTokens')
+        inputFiles = [file('src/test/01-input/treeAllowedTokens/Test.relast'),
+                      file('src/test/01-input/treeAllowedTokens/Test.connect'),
+                      file('src/test/01-input/treeAllowedTokens/TestDependencies.connect')]
+        rootNode = 'Root'
+    }
+    relast {
+        useJastAddNames = true
+        grammarName = 'src/test/03-after-relast/treeAllowedTokens/treeAllowedTokens'
+        serializer = 'jackson'
+    }
+    jastadd {
+        jastAddList = 'JastAddList'
+        packageName = 'treeAllowedTokens.ast'
+        inputFiles = [file('src/test/01-input/treeAllowedTokens/Test.jadd')]
+    }
+}
+```
+
+[preprocessor-plugin]: https://git-st.inf.tu-dresden.de/jastadd/testing

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/).