From b197dc8f052ebbf1778039d4b40f817c429fc560 Mon Sep 17 00:00:00 2001
From: mo8it <mo8it@proton.me>
Date: Sat, 4 Nov 2023 13:30:14 +0100
Subject: [PATCH] Update docs

---
 advlabdb/adminModelViews.py              |  2 +-
 advlabdb/templates/docs/admin.jinja.html | 92 ++++++++++++++++++++++--
 2 files changed, 88 insertions(+), 6 deletions(-)

diff --git a/advlabdb/adminModelViews.py b/advlabdb/adminModelViews.py
index a3af543..6437728 100644
--- a/advlabdb/adminModelViews.py
+++ b/advlabdb/adminModelViews.py
@@ -397,7 +397,7 @@ class SemesterView(SecureAdminModelView):
 
     form_args = {
         "done": {
-            "description": "Setting a semester as done prevents assistants from changing or even seeing marks in this semester. Setting a semester as done sets older semesters as done, too. Only set the semester as done if all marks in the semester and all previous semesters are already set."
+            "description": "Setting a semester as done prevents assistants from changing or even seeing marks in this semester. Setting a semester as done sets older semesters as done, too. Only set a semester as done if all marks in that semester and all previous semesters are already set."
         },
     }
 
diff --git a/advlabdb/templates/docs/admin.jinja.html b/advlabdb/templates/docs/admin.jinja.html
index f16d2bb..73497c8 100644
--- a/advlabdb/templates/docs/admin.jinja.html
+++ b/advlabdb/templates/docs/admin.jinja.html
@@ -82,7 +82,7 @@
 
 <p>
     Every part student has a final part mark shown in this table.
-    The final part mark is calculated as explained in <a href="#experiment">Experiment</a>.
+    The final part mark is calculated as explained in <a href="#semester_experiment">Semester Experiment</a>.
     Normally, this final part mark is the one relevant for the transcript of records of students.
 </p>
 
@@ -193,16 +193,98 @@
     This mark is calculated with respect to the weights of the related <a href="#semester_experiment">semester experiment</a>.
 </p>
 
-<!-- TODO
 <h4 id="experiment">Experiment</h4>
-<p></p>
+<p>This table shows all experiments, not only in your active semester.</p>
+
+<p>
+    Experiments that are marked as "active" will be present in new semesters.
+    Make sure to active/deactivate experiments before creating a new semester.
+</p>
 
 <h4 id="semester_experiment">Semester Experiment</h4>
-<p></p>
+<p>This table shows the semester experiments in your active semester.</p>
+
+<p>
+    A semester experiment is an <a href="#experiment">experiment</a> that takes place in a specific <a href="#semester">semester</a>.
+</p>
+
+<p>
+    Assistants and mark weightings are assigned to these semester experiments.
+    These assignments are transfered to the next semester if the related <a href="#experiment">experiment</a> was active before creating the new semester.
+</p>
+
+<p>Mark weightings consist of oral, protocol and final weightings.</p>
+
+<p>
+    The oral weighting and protocol weightings are between 0 and 1 and have to add up to 1.
+    By default, these weightings should both be 0.5, but you can for example have an oral weighting of 0.25 and a protocol weighting of 0.75.
+</p>
+
+<p>
+    The final weighting has to be a value between 0 and 1.
+    By default, its value should be 1.
+    But you can choose a value lower than 1 in case an experiment is easier than others.
+</p>
+
+<p>
+    The final part mark for a student is calculated by summing the following experession over <code>i</code> and then dividing through the sum of <code>f_i</code>:
+</p>
+
+<p>
+    <code>f_i * (ow_i * o_i + pw_i * p_i)</code>
+</p>
+
+<ul>
+    <li>
+        <code>i</code> is the index of a semester experiment.
+        The sum over <code>i</code> is done only over the semester experiments that a student has in that part.
+    </li>
+    <li>
+        <code>f_i</code> is the final part mark for the semester experiment <code>i</code>.
+    </li>
+    <li>
+        <code>ow_i</code> is the oral weighting.
+    </li>
+    <li>
+        <code>o_i</code> is the oral mark.
+    </li>
+    <li>
+        <code>pw_i</code> is the protocol weighting.
+    </li>
+    <li>
+        <code>p_i</code> is the protocol mark.
+    </li>
+</ul>
+
+<p>
+    The result after the division is rounded to an integer using the "round half up" strategy.
+    This means that <code>x.5</code> is always rounded up to <code>x+1</code>.
+    Values between <code>x.5</code> and <code>x+1</code> (closed interval) are rounded up to <code>x+1</code>.
+    Values higher than <code>x</code> and lower than <code>x.5</code> are rounded down to <code>x</code>.
+</p>
+
+<p>
+    In case you change the weightings during a semester (some marks are already set), all part and experiment marks will be automatically updated.
+</p>
 
 <h4 id="semester">Semester</h4>
-<p></p>
+<p>This table shows all semesters.</p>
 
+<p>
+    Before creating a new semester, make sure to read all notes in the form that shows up after pressing the "Create" button.
+</p>
+
+<p>
+    You can and should set a semester as "done" by clicking on the edit button near that semester, then clicking the "done" checkbox and then "Save".
+</p>
+
+<p>
+    Setting a semester as done prevents assistants from changing or even seeing marks in this semester.
+    Setting a semester as done sets older semesters as done, too.
+    Only set a semester as done if all marks in that semester and all previous semesters are already set.
+</p>
+
+<!-- TODO
 <h4 id="part">Part</h4>
 <p></p>