From 9a1d3a9081ff8a2461ce857879a38572acc5904d Mon Sep 17 00:00:00 2001
From: 9Lukas5 <lukas.wiest@infinite-tech.solutions>
Date: Fri, 12 Feb 2021 18:33:59 +0100
Subject: [PATCH] feat: add moodle-plugin docs

---
 docs/moodle-plugin/index.md | 118 ++++++++++++++++++++++++++++++++++++
 mkdocs.yml                  |   1 +
 2 files changed, 119 insertions(+)
 create mode 100644 docs/moodle-plugin/index.md

diff --git a/docs/moodle-plugin/index.md b/docs/moodle-plugin/index.md
new file mode 100644
index 0000000..b5571de
--- /dev/null
+++ b/docs/moodle-plugin/index.md
@@ -0,0 +1,118 @@
+# Moodle-Plugin
+
+This documentation part describes the source-code file-structure,
+database layout
+and functionality of our moodle-plugin.
+
+## Repo/File-Structure
+
+The plugin repo is located at the HFT Stuttgart transfer portal [here][plugin-repo].
+
+It contains a license file,
+a readme linking to this documentation
+and the plugin code in a subfolder.
+
+This plugin is a moodle [assign-submission-plugin][moodle-assign-submission-plugins].
+
+### Version.php
+
+This file set's a few plugin variables read from moodle.
+The `plugin release` variable should contain a version number in the [semantic-version scheme][semver].
+The `plugin version` needs to match the `plugin release`. Minor and patch part of the semantic-version have to be padded to three digits.
+
+### Settings.php
+
+This defines the plugin settings, configurable from the moodle plugin administration.
+
+Defined options are the default enabled state for assignments
+and the backend url.
+
+### Locallib.php
+
+This file holds the plugin class that extends the `assign_submission_plugin`.
+
+On the top multiple requires are done for the additional files in the subfolders `models` and `utils`.
+Next starts the class definition,
+overriding the parent classes abstract methods getting called on various actions from the Moodle-UI.
+
+### Models
+
+| file            | content description                                                      |
+| --------------- | ------------------------------------------------------------------------ |
+| `DttResult.php` | classes `DttResult` and `DttResultSummary` for transferring from backend |
+
+### Utils
+
+| file           | content description                          |
+| -------------- | -------------------------------------------- |
+| `backend.php`  | logic to communicate with the backend server |
+| `database.php` | logic talking to the database                |
+| `view.php`     | logic to react to frontend actions           |
+
+## Database
+
+Results from tests are delivered in a summary object,
+containing some meta data and an array of single result objects.
+
+Both classes are persisted in their own database table.
+Both are matched by the assignment and submission id to which they belong.
+An additional redundant relationship between results and summaries was not implemented.
+
+```plantuml
+
+entity "assignsubmission_dtt_summary" as summary {
+    id: int <<generated>>
+    --
+    assignment_id: int <<FK>>
+    submission_id: int <<FK>>
+    timestamp: int
+    global_stacktrace: text
+}
+
+entity "assignsubmission_dtt_result" as results {
+    id: int <<generated>>
+    --
+    assignment_id: int <<FK>>
+    submission_id: int <<FK>>
+    --
+    name: char
+    state: int
+    failure_type: char
+    failure_reason: char
+    stacktrace: text
+    column_number: int
+    line_number: int
+    position: int
+}
+
+entity assign {}
+entity assign_submission {}
+
+assign "id" ||--|{ "assignment_id" summary
+assign_submission "id" ||-up-|{ "submission_id" summary
+
+assign "id" ||--|{ "assignment_id" results
+assign_submission "id" ||-up-|{ "submission_id" results
+
+```
+
+## Functionality
+
+This plugin offers the possibility to create an assignment
+that accepts an URL to a Git-repo or a zipped code base as a submission.
+
+The lecturer who creates the assignment must provide a Git repo that contains the test code
+and specify a Docker image available on DockerHub that will be used as a test runner.
+
+When a submission is made, it is sent to the backend server.
+There it is tested against the test code in the test runner defined by the lecturer.
+The connection from the plugin remains open all the time. After completing the test,
+the backend closes the connection with the results as a response.
+
+The received results are persisted in the database.
+In the view of a submission, a summary table is displayed at the top
+and each individual result in a second table below.
+
+[moodle-assign-submission-plugins]: https://docs.moodle.org/dev/Assign_submission_plugins
+[plugin-repo]: https://transfer.hft-stuttgart.de/gitlab/dtt/moodle-plugin
+[semver]: https://semver.org/
diff --git a/mkdocs.yml b/mkdocs.yml
index 1d0f8d7..2f0c98b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -15,6 +15,7 @@ nav:
     - Changelog: 'changelog.md'
     - License: 'license.md'
   - Usage: 'usage.md'
+  - Moodle-Plugin: 'moodle-plugin/index.md'
   - Testrunner:
     - Index: 'testrunner/index.md'
   - Contribute:
-- 
GitLab