From 0af50e07ac91a861f167ee7f49d55c48b9ffd0cc Mon Sep 17 00:00:00 2001
From: rschoene <rene.schoene@tu-dresden.de>
Date: Tue, 2 Feb 2021 11:35:24 +0100
Subject: [PATCH] Switch to mkdocs

---
 .gitlab-ci.yml                                |  24 +++----
 pages/.gitignore                              |   3 +-
 pages/Makefile                                |  20 ------
 pages/conf.py                                 |  59 ------------------
 pages/custom_theme/footer.html                |  11 ++++
 pages/{ => docs}/DSL.md                       |   0
 pages/{ => docs}/Inner-workings.md            |   8 +--
 pages/{ => docs}/Learner.md                   |   0
 pages/{ => docs}/MachineLearning.md           |   0
 pages/{ => docs}/Model-description.md         |   0
 pages/{ => docs}/config.md                    |   0
 pages/{ => docs}/contributing.md              |   2 +-
 .../img}/config-eraser-binding.png            | Bin
 .../img}/config-mqtt-binding.png              | Bin
 pages/{_static => docs/img}/item-history.png  | Bin
 pages/{_static => docs/img}/item-history.uxf  |   0
 pages/{_static => docs/img}/rules-object.png  | Bin
 pages/{_static => docs/img}/rules-object.uxf  |   0
 .../{_static => docs/img}/rules-sequence.png  | Bin
 .../{_static => docs/img}/rules-sequence.uxf  |   0
 pages/{_static => docs/img}/rules.uxf         |   0
 pages/{_static => docs/img}/swagger-ui.png    | Bin
 pages/docs/index.md                           |  11 ++++
 pages/{ => docs}/mqtt.md                      |   0
 pages/{ => docs}/openhab-binding.md           |   6 +-
 pages/{ => docs}/setup.md                     |   0
 pages/{ => docs}/working.md                   |   2 +-
 pages/index.rst                               |  44 -------------
 pages/make.bat                                |  35 -----------
 pages/mkdocs.yml                              |  23 +++++++
 30 files changed, 69 insertions(+), 179 deletions(-)
 delete mode 100644 pages/Makefile
 delete mode 100644 pages/conf.py
 create mode 100644 pages/custom_theme/footer.html
 rename pages/{ => docs}/DSL.md (100%)
 rename pages/{ => docs}/Inner-workings.md (97%)
 rename pages/{ => docs}/Learner.md (100%)
 rename pages/{ => docs}/MachineLearning.md (100%)
 rename pages/{ => docs}/Model-description.md (100%)
 rename pages/{ => docs}/config.md (100%)
 rename pages/{ => docs}/contributing.md (96%)
 rename pages/{_static => docs/img}/config-eraser-binding.png (100%)
 rename pages/{_static => docs/img}/config-mqtt-binding.png (100%)
 rename pages/{_static => docs/img}/item-history.png (100%)
 rename pages/{_static => docs/img}/item-history.uxf (100%)
 rename pages/{_static => docs/img}/rules-object.png (100%)
 rename pages/{_static => docs/img}/rules-object.uxf (100%)
 rename pages/{_static => docs/img}/rules-sequence.png (100%)
 rename pages/{_static => docs/img}/rules-sequence.uxf (100%)
 rename pages/{_static => docs/img}/rules.uxf (100%)
 rename pages/{_static => docs/img}/swagger-ui.png (100%)
 create mode 100644 pages/docs/index.md
 rename pages/{ => docs}/mqtt.md (100%)
 rename pages/{ => docs}/openhab-binding.md (97%)
 rename pages/{ => docs}/setup.md (100%)
 rename pages/{ => docs}/working.md (94%)
 delete mode 100644 pages/index.rst
 delete mode 100644 pages/make.bat
 create mode 100644 pages/mkdocs.yml

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index ef6a5286..1ed8784d 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -39,6 +39,8 @@ test:
   tags:
     - docker
   stage: test
+  needs:
+    - build
   script:
     - ./gradlew --continue --console=plain --info check jacocoTestReport
   artifacts:
@@ -51,8 +53,8 @@ test:
 coverage:
   image: python:3.7.1-alpine
   stage: report
-  dependencies:
-  - test
+  needs:
+    - test
   script:
 #    - ./gradlew --continue --console=plain -x test jacocoTestReport
     - pip install --user untangle
@@ -69,7 +71,7 @@ ragdoc_build:
     name: "git-st.inf.tu-dresden.de:4567/jastadd/ragdoc-builder"
     entrypoint: [""]
   stage: ragdoc_build
-  dependencies:
+  needs:
     - build
   script:
     - JAVA_FILES=$(find eraser-base/src/ -name '*.java')
@@ -83,29 +85,29 @@ ragdoc_view:
     name: "git-st.inf.tu-dresden.de:4567/jastadd/ragdoc-view:relations"
     entrypoint: [""]
   stage: ragdoc_view
-  dependencies:
+  needs:
     - ragdoc_build
   script:
     - DATA_DIR=$(pwd -P)/data
-    - mkdir -p pages/_static/ragdoc
-    - OUTPUT_DIR=$(pwd -P)/pages/_static/ragdoc
+    - mkdir -p pages/docs/ragdoc
+    - OUTPUT_DIR=$(pwd -P)/pages/docs/ragdoc
     - cd /ragdoc-view
     - ( cd src/ && rm -rf data && ln -s $DATA_DIR )
     - /ragdoc-view/build-view.sh --output-path=$OUTPUT_DIR
     - ls -lah $OUTPUT_DIR
   artifacts:
     paths:
-      - "pages/_static/ragdoc"
+      - "pages/docs/ragdoc"
 
 pages:
   image: python:3.7-alpine
   stage: publish
-  dependencies:
+  needs:
     - ragdoc_view
   before_script:
-    - pip install -U sphinx sphinx-rtd-theme recommonmark sphinxemoji sphinx-markdown-tables
+    - pip install -U mkdocs mkdocs-macros-plugin mkdocs-git-revision-date-plugin
   script:
-    - sphinx-build -b html pages/ public
+    - cd pages && mkdocs build
   artifacts:
     paths:
-    - public
+    - "pages/site"
diff --git a/pages/.gitignore b/pages/.gitignore
index 87174b68..8b6d81db 100644
--- a/pages/.gitignore
+++ b/pages/.gitignore
@@ -1 +1,2 @@
-/public/
+/site/
+/docs/ragdoc/
diff --git a/pages/Makefile b/pages/Makefile
deleted file mode 100644
index 7878ee53..00000000
--- 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/conf.py b/pages/conf.py
deleted file mode 100644
index e96bf781..00000000
--- a/pages/conf.py
+++ /dev/null
@@ -1,59 +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 = 'Eraser'
-copyright = '2021, René Schöne'
-author = 'René Schöne'
-
-
-# -- 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 = ['public', 'Thumbs.db', '.DS_Store']
-
-
-# -- 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 00000000..e76f0a2b
--- /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.revision_date %}
+<small><br><i>Last updated {{ page.meta.revision_date.strftime('%B %d, %Y at %H:%M') }}</i></small>
+{% endif %}
+</p>
+{% endblock %}
diff --git a/pages/DSL.md b/pages/docs/DSL.md
similarity index 100%
rename from pages/DSL.md
rename to pages/docs/DSL.md
diff --git a/pages/Inner-workings.md b/pages/docs/Inner-workings.md
similarity index 97%
rename from pages/Inner-workings.md
rename to pages/docs/Inner-workings.md
index ddd02b2f..ebbb861f 100644
--- a/pages/Inner-workings.md
+++ b/pages/docs/Inner-workings.md
@@ -1,6 +1,6 @@
 # Inner workings
 
-Please also refer to the [API documentation](_static/ragdoc/index.html)
+Please also refer to the [API documentation](ragdoc/index.html)
 
 ## openHAB synchronization via MQTT
 
@@ -35,7 +35,7 @@ However, those two are intended to be independent of each other.
 
 For retrieving the history, an asynchronous approach was chosen and is described in the following. The sequence diagram shows the important methods called, where ItemType denotes a specific subclass of Item, e.g., `ColorItem` or `ItemWithDoubleState`, and Item denotes the general, common superclass `Item`.
 
-![item-history](_static/item-history.png)
+![item-history](img/item-history.png)
 
 To get the history, `getHistory` is called on a specific item returning a list of datapoints of a matching type, e.g., a list of `DoubleStatePoint` for an `ItemWithDoubleState`.
 
@@ -48,7 +48,7 @@ This token contains the history, and is returned by the `_history` attribute. If
 
 For events in rules to trigger, `ItemObserver` objects are used. The following figure shows three rules (A, B, C) triggered by two different items (`item1` und `item2`):
 
-![rules-object](_static/rules-object.png)
+![rules-object](img/rules-object.png)
 
 To get those wirings, the following code can be used:
 
@@ -79,7 +79,7 @@ rC.activateFor(item1);
 Changes to `item1` trigger all three rules, whereas changing `item2` only triggers the second rule B.
 Triggering a rule works as follows:
 
-![rules-sequence](_static/rules-sequence.png)
+![rules-sequence](img/rules-sequence.png)
 
 When the state of `item1` is changed, its observer checks, whether the new change is different to the previous change. If that is the case, it triggers all associated rules, i.e, it calls `rule.trigger()` for every rule in the `TriggeredRuleList`.
 The rule checks all conditions (if any), and if all hold, executes all actions (if any).
diff --git a/pages/Learner.md b/pages/docs/Learner.md
similarity index 100%
rename from pages/Learner.md
rename to pages/docs/Learner.md
diff --git a/pages/MachineLearning.md b/pages/docs/MachineLearning.md
similarity index 100%
rename from pages/MachineLearning.md
rename to pages/docs/MachineLearning.md
diff --git a/pages/Model-description.md b/pages/docs/Model-description.md
similarity index 100%
rename from pages/Model-description.md
rename to pages/docs/Model-description.md
diff --git a/pages/config.md b/pages/docs/config.md
similarity index 100%
rename from pages/config.md
rename to pages/docs/config.md
diff --git a/pages/contributing.md b/pages/docs/contributing.md
similarity index 96%
rename from pages/contributing.md
rename to pages/docs/contributing.md
index 48dad825..bddb5e91 100644
--- a/pages/contributing.md
+++ b/pages/docs/contributing.md
@@ -1,6 +1,6 @@
 # Contributing
 
-Please also refer to the [API documentation](_static/ragdoc/index.html)
+Please also refer to the [API documentation](ragdoc/index.html)
 
 Steps to create the initial multi-project setup from a single-project setup
 
diff --git a/pages/_static/config-eraser-binding.png b/pages/docs/img/config-eraser-binding.png
similarity index 100%
rename from pages/_static/config-eraser-binding.png
rename to pages/docs/img/config-eraser-binding.png
diff --git a/pages/_static/config-mqtt-binding.png b/pages/docs/img/config-mqtt-binding.png
similarity index 100%
rename from pages/_static/config-mqtt-binding.png
rename to pages/docs/img/config-mqtt-binding.png
diff --git a/pages/_static/item-history.png b/pages/docs/img/item-history.png
similarity index 100%
rename from pages/_static/item-history.png
rename to pages/docs/img/item-history.png
diff --git a/pages/_static/item-history.uxf b/pages/docs/img/item-history.uxf
similarity index 100%
rename from pages/_static/item-history.uxf
rename to pages/docs/img/item-history.uxf
diff --git a/pages/_static/rules-object.png b/pages/docs/img/rules-object.png
similarity index 100%
rename from pages/_static/rules-object.png
rename to pages/docs/img/rules-object.png
diff --git a/pages/_static/rules-object.uxf b/pages/docs/img/rules-object.uxf
similarity index 100%
rename from pages/_static/rules-object.uxf
rename to pages/docs/img/rules-object.uxf
diff --git a/pages/_static/rules-sequence.png b/pages/docs/img/rules-sequence.png
similarity index 100%
rename from pages/_static/rules-sequence.png
rename to pages/docs/img/rules-sequence.png
diff --git a/pages/_static/rules-sequence.uxf b/pages/docs/img/rules-sequence.uxf
similarity index 100%
rename from pages/_static/rules-sequence.uxf
rename to pages/docs/img/rules-sequence.uxf
diff --git a/pages/_static/rules.uxf b/pages/docs/img/rules.uxf
similarity index 100%
rename from pages/_static/rules.uxf
rename to pages/docs/img/rules.uxf
diff --git a/pages/_static/swagger-ui.png b/pages/docs/img/swagger-ui.png
similarity index 100%
rename from pages/_static/swagger-ui.png
rename to pages/docs/img/swagger-ui.png
diff --git a/pages/docs/index.md b/pages/docs/index.md
new file mode 100644
index 00000000..a341cbda
--- /dev/null
+++ b/pages/docs/index.md
@@ -0,0 +1,11 @@
+# Documentation of Eraser
+
+First, setup eraser following the README in the main repository: [dev](https://git-st.inf.tu-dresden.de/OpenLicht/eraser/blob/dev/README.md) | [master](https://git-st.inf.tu-dresden.de/OpenLicht/eraser/blob/master/README.md)
+To configure the system, read the [configuration page](config).
+
+For an overview of the model, check out the [Model description](Model-description).
+If you need more details, dive into the [inner workings](Inner-workings) (now with colorful images!), [insights for working with the model](working) the [description of machine learning](MachineLearning) (with code examples) or the [description of Learner implementation](Learner) (only in German).
+To be able to read in models, a [dedicated DSL](DSL) must be used.
+
+Further, the updated [configuration settings regarding MQTT 1.x and 2.x](mqtt) as well as the [Setup guide to connect to openHAB](openhab-binding) (only in German) are found in this wiki.
+For contributing, please see [contribution guideline](contributing).
diff --git a/pages/mqtt.md b/pages/docs/mqtt.md
similarity index 100%
rename from pages/mqtt.md
rename to pages/docs/mqtt.md
diff --git a/pages/openhab-binding.md b/pages/docs/openhab-binding.md
similarity index 97%
rename from pages/openhab-binding.md
rename to pages/docs/openhab-binding.md
index 9cc2856a..7be215a0 100644
--- a/pages/openhab-binding.md
+++ b/pages/docs/openhab-binding.md
@@ -130,7 +130,7 @@ Grundlage auf der openHAB-Seite ist ein installiertes MQTT-Binding in Version 2,
 
 In der PaperUI muss ein MQTT-Broker-Thing angelegt werden, entweder ein SystemBroker oder ein lokaler Broker, wie im Beispiel gezeigt:
 
-![MQTT Binding Config](_static/config-mqtt-binding.png)
+![MQTT Binding Config](img/config-mqtt-binding.png)
 
 Zusätzlich muss ein Eraser-Thing angelegt werden, welches den Namen des oben genannten Brokers in den Einstellung gesetzt hat (hier im Beispiel `local-mqtt-broker`).
 Wahlweise können Updates von allen Items (`Publish All` aktiviert), oder nur von Items in einer Gruppe (`Publish All` deaktiviert und `Publish Group` ausgewählt) an Eraser gesendet werden.
@@ -140,7 +140,7 @@ Weiterhin ist zu beachten, dass die MQTT-Topics hier und bei der Eraser-Konfigur
 - `openhab.Base-Topic == eraser.outgoing` (im Beispiel `oh2/in`)
 - `openhab.Outgoing-Topic == eraser.incoming` (im Beispiel `oh2/out`)
 
-![Eraser Binding Config](_static/config-eraser-binding.png)
+![Eraser Binding Config](img/config-eraser-binding.png)
 
 ## Swagger-UI für die REST-API der Knowledge-Base
 
@@ -154,4 +154,4 @@ python forward.py
 Abhängigkeiten sind `flask`, `flask_restplus` und `requests`.
 Nach Starten sieht die Oberfläche aktuell wie folgt aus:
 
-![Swagger-UI Startseite](_static/swagger-ui.png)
+![Swagger-UI Startseite](img/swagger-ui.png)
diff --git a/pages/setup.md b/pages/docs/setup.md
similarity index 100%
rename from pages/setup.md
rename to pages/docs/setup.md
diff --git a/pages/working.md b/pages/docs/working.md
similarity index 94%
rename from pages/working.md
rename to pages/docs/working.md
index 811a0127..ec9110a2 100644
--- a/pages/working.md
+++ b/pages/docs/working.md
@@ -15,4 +15,4 @@ Synchronisation between eraser and openHAB itself currently includes only states
 
 ## Documentation
 
-When working and especially when extending eraser, it is highly recommended to generated the [RagDoc documentation](Ragdoc) as a reference manual.
+When working and especially when extending eraser, it is highly recommended to use the [API documentation](ragdoc/index.html) as a reference manual.
diff --git a/pages/index.rst b/pages/index.rst
deleted file mode 100644
index 9865d2d7..00000000
--- a/pages/index.rst
+++ /dev/null
@@ -1,44 +0,0 @@
-.. Eraser documentation master file, created by
-   sphinx-quickstart on Mon Feb  1 11:27:36 2021.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to Eraser's documentation!
-==================================
-
-First, `setup <setup>`_ eraser following the README in the main repository: `dev <https://git-st.inf.tu-dresden.de/OpenLicht/eraser/blob/dev/README.md>`_ | `master <https://git-st.inf.tu-dresden.de/OpenLicht/eraser/blob/master/README.md>`_
-To configure the system, read the `configuration page <config>`_.
-
-For an overview of the model, check out the `Model description <Model-description>`_.
-If you need more details, dive into the `inner workings <Inner-workings>`_ (now with colorful images!), `insights for working with the model <working>`_ the `description of machine learning <MachineLearning>`_ (with code examples)_ or the `description of Learner implementation <Learner>`_ (only in German).
-To be able to read in models, a `dedicated DSL <DSL>`_ must be used.
-
-Further, the updated `configuration settings regarding MQTT 1.x and 2.x <mqtt>`_ as well as the `Setup guide to connect to openHAB <openhab-binding>`_ (only in German) are found in this wiki.
-To create the documentation for the generated JastAdd code, follow the `ragdoc documentation guidelines <Ragdoc>`_.
-
-For contributing, please see `contribution guideline <contributing>`_.
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
-   setup.md
-   config.md
-   Model-description.md
-   Inner-workings.md
-   working.md
-   MachineLearning.md
-   Learner.md
-   DSL.md
-   mqtt.md
-   openhab-binding.md
-   contributing.md
-   `API documentation <_static/ragdoc/index.html>`_
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/pages/make.bat b/pages/make.bat
deleted file mode 100644
index c6abfba4..00000000
--- 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/mkdocs.yml b/pages/mkdocs.yml
new file mode 100644
index 00000000..bfb8fc6c
--- /dev/null
+++ b/pages/mkdocs.yml
@@ -0,0 +1,23 @@
+site_name: Documentation of Eraser
+nav:
+  - setup.md
+  - config.md
+  - Model-description.md
+  - Inner-workings.md
+  - working.md
+  - MachineLearning.md
+  - Learner.md
+  - DSL.md
+  - mqtt.md
+  - openhab-binding.md
+  - contributing.md
+  - API documentation: ragdoc/index.html
+theme:
+  name: readthedocs
+  custom_dir: custom_theme/
+plugins:
+  - search
+  - git-revision-date:
+      as_datetime: True
+  - macros
+repo_url: https://git-st.inf.tu-dresden.de/OpenLicht/eraser
-- 
GitLab