Verified Commit 9a1d3a90 authored by Lukas Wiest's avatar Lukas Wiest 🚂

feat: add moodle-plugin docs

parent 619b890a
Pipeline #1976 passed with stages
in 2 minutes and 18 seconds
# 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/
......@@ -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:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment