From 12749f95d06fa9c096412cd284decdc55494c955 Mon Sep 17 00:00:00 2001
From: rschoene <rene.schoene@tu-dresden.de>
Date: Mon, 8 Nov 2021 10:32:17 +0100
Subject: [PATCH] Updating documentation.

---
 pages/docs/adding.md | 16 +++++++++++-----
 pages/docs/using.md  |  6 +++---
 pages/mkdocs.yml     | 25 ++++++++++++++++---------
 3 files changed, 30 insertions(+), 17 deletions(-)

diff --git a/pages/docs/adding.md b/pages/docs/adding.md
index f777e32..7d25f85 100644
--- a/pages/docs/adding.md
+++ b/pages/docs/adding.md
@@ -51,7 +51,7 @@ You might need to add another task for [compiling relast specifications](#compil
 
 ## Build from source
 
-If you want to use `RagConnect`, the currently suggested way is to first build the jar from the [RagConnect repository](https://git-st.inf.tu-dresden.de/jastadd/ragconnect):
+If you want to plan to extend `RagConnect`, the suggested way is to first build the jar from the [RagConnect repository](https://git-st.inf.tu-dresden.de/jastadd/ragconnect) (if you only want to _use_ it, consider using [the packaged version](#use-packaged-version)).
 
 ```bash
 git clone https://git-st.inf.tu-dresden.de/jastadd/ragconnect.git
@@ -60,14 +60,17 @@ cd ragconnect
 ls ragconnect.base/build/libs/
 ```
 
-This `ragconnect-<version>.jar` can then be copied to your project. Please note, that you can safely use `ragconnect.jar` as filename, because the version can always be printed using `java -jar path/to/ragconnect.jar --version`.
+This `ragconnect-<version>.jar` can then be copied to your project.
+Please note, that you can safely use `ragconnect.jar` as filename, because the version can always be printed using `java -jar path/to/ragconnect.jar --version`.
 
 ```bash
 cp ragconnect.base/build/libs/ragconnect-<version>.jar ../your-project/libs/ragconnect.jar
 cd ../your-project/
 ```
 
-Finally, this jar has to be integrated into your build process. In case, [Gradle](https://gradle.org/) is used, a task could look like the following (example taken from the [ros2rag usecase](https://git-st.inf.tu-dresden.de/jastadd/ros2rag)). The path to the jar file may need to be changed according to your project structure.
+Finally, this jar has to be integrated into your build process.
+In case, [Gradle](https://gradle.org/) is used, a task could look like the following (example taken from the [ros2rag use case](https://git-st.inf.tu-dresden.de/jastadd/ros2rag)).
+The path to the jar file may need to be changed according to your project structure.
 
 ```groovy
 task ragConnect(type: JavaExec) {
@@ -89,7 +92,10 @@ You might need to add another task for [compiling relast specifications](#compil
 
 ## Compiling RelAst specifications
 
-The task to compile `RagConnect` specifications is typically accompanied with a task to invoke the [RelAst compiler](http://relational-rags.eu/) and the [JastAdd gradle plugin](https://plugins.gradle.org/plugin/org.jastadd). The additional arguments `--useJastAddNames`, `--listClass`, `--jastAddList` and `--resolverHelper` to relast are not required. Please see the user manual of the RelAst compiler for more information.
+The task to compile `RagConnect` specifications is typically accompanied by a task to invoke the [RelAst compiler](http://relational-rags.eu/) and the [JastAdd gradle plugin](https://plugins.gradle.org/plugin/org.jastadd).
+Currently, the parameter `--useJastAddNames` is **required**, and it may cause incompatibilities if not set.
+The additional arguments `--listClass`, `--jastAddList` and `--resolverHelper` to relast are not required.
+Please see the user manual of the RelAst compiler for more information.
 
 ```groovy
 task relastToJastAdd(type: JavaExec) {
@@ -122,7 +128,7 @@ relastToJastAdd.dependsOn ragConnect
 ## Introduced dependencies
 
 RagConnect itself does not introduce dependencies.
-However, depending on the selected protocols (see [compiler options](using#compiler-options)), additional dependencies are required.
+However, depending on the selected protocols (see [compiler options](/using#compiler-options)), additional dependencies are required.
 
 | Protocol | Dependency (Gradle format) | Remarks |
 |---|---|---|
diff --git a/pages/docs/using.md b/pages/docs/using.md
index a8fc0da..43df073 100644
--- a/pages/docs/using.md
+++ b/pages/docs/using.md
@@ -46,7 +46,7 @@ eq A.getB().input() = getInput();
 ```
 
 In other words, `OutputOnA` depends on `Input` of the same node, and `OutputOnB` depends on `Input` of its parent node.
-Currently, those dependencies have to be explicitely written down. It is expected, that in future version, this won't be necessary anymore.
+Currently, those dependencies have to be explicitly written down. It is expected, that in future version, this won't be necessary anymore.
 This happens also in the DSL (dependencies have to be named to uniquely identify them):
 
 ```java
@@ -57,7 +57,7 @@ B.OutputOnB canDependOn A.Input as dependencyB ;
 
 ## Using generated code
 
-After specifying everything, code will be generated if [setup properly](adding).
+After specifying everything, code will be generated if [setup properly](/adding).
 Let's create an AST in some driver code:
 
 ```java
@@ -96,7 +96,7 @@ The first parameter of those connect-methods is always an URI-like String, to id
 In case of MQTT, the server is the host running an MQTT broker, and the path is equal to the topic to publish or subscribe to.
 Please note, that the first leading slash (`/`) is removed for MQTT topics, e.g., for `A.Input` the topic is actually `topic/for/input`.
 
-For sending endpoints, there is a second boolean parameter to specify whether the current value shall be send immediately after connecting.
+For sending endpoints, there is a second boolean parameter to specify whether the current value shall be sent immediately after connecting.
 
 ## Communication protocol characteristics
 
diff --git a/pages/mkdocs.yml b/pages/mkdocs.yml
index 6363c73..8bfa0d6 100644
--- a/pages/mkdocs.yml
+++ b/pages/mkdocs.yml
@@ -1,15 +1,24 @@
 site_name: RagConnect
+repo_url: https://git-st.inf.tu-dresden.de/jastadd/ragconnect
+site_dir: ../public
+
 nav:
-  - use_cases.md
-  - adding.md
-  - inner-workings.md
-  - using.md
-  - extending.md
-  - changelog.md
-  - API documentation: ragdoc/index.html
+  - "RagConnect by Example": using.md
+  - "Use Cases": use_cases.md
+  - "Adding RagConnect to your project": adding.md
+  - "Inner workings": inner-workings.md
+  - "Extending RagConnect": extending.md
+  - "Changelog": changelog.md
+  - "API documentation": ragdoc/index.html
+
 theme:
   name: readthedocs
   custom_dir: custom_theme/
+
+markdown_extensions:
+  - toc:
+      permalink: 
+
 plugins:
   - search
   - git-revision-date-localized:
@@ -18,5 +27,3 @@ plugins:
       locale: en
       fallback_to_build_date: True
   - macros
-repo_url: https://git-st.inf.tu-dresden.de/jastadd/ragconnect
-site_dir: ../public
-- 
GitLab