From 58a13bf05a5e6eecf429913267e21ac9f05ffd8a Mon Sep 17 00:00:00 2001
From: Robin Sonnabend <robin@fsmpi.rwth-aachen.de>
Date: Tue, 28 Feb 2017 15:00:06 +0100
Subject: [PATCH] More documentation

---
 models/database.py           | 10 ++++++++++
 server.py                    | 11 ++++++++---
 shared.py                    |  8 ++++++++
 templates/documentation.html | 37 ++++++++++++++++++++++++++++++------
 todostates.py                |  1 +
 5 files changed, 58 insertions(+), 9 deletions(-)

diff --git a/models/database.py b/models/database.py
index 029b833..baa6790 100644
--- a/models/database.py
+++ b/models/database.py
@@ -391,6 +391,16 @@ class TodoState(Enum):
     def get_name(self):
         STATE_TO_NAME, NAME_TO_STATE = make_states(TodoState)
         return STATE_TO_NAME[self]
+    
+    @staticmethod
+    def get_name_to_state():
+        STATE_TO_NAME, NAME_TO_STATE = make_states(TodoState)
+        return NAME_TO_STATE
+
+    @staticmethod
+    def get_state_to_name():
+        STATE_TO_NAME, NAME_TO_STATE = make_states(TodoState)
+        return STATE_TO_NAME
 
     def needs_date(self):
         return self in [TodoState.after, TodoState.before]
diff --git a/server.py b/server.py
index ce68e5e..854dea0 100755
--- a/server.py
+++ b/server.py
@@ -19,9 +19,9 @@ from datetime import datetime
 import math
 
 import config
-from shared import db, date_filter, datetime_filter, date_filter_long, time_filter, ldap_manager, security_manager, current_user, check_login, login_required, group_required, class_filter
+from shared import db, date_filter, datetime_filter, date_filter_long, time_filter, ldap_manager, security_manager, current_user, check_login, login_required, group_required, class_filter, needs_date_test, todostate_name_filter, code_filter
 from utils import is_past, mail_manager, url_manager, get_first_unused_int, set_etherpad_text, get_etherpad_text, split_terms, optional_int_arg
-from models.database import ProtocolType, Protocol, DefaultTOP, TOP, Document, Todo, Decision, MeetingReminder, Error, TodoMail, DecisionDocument
+from models.database import ProtocolType, Protocol, DefaultTOP, TOP, Document, Todo, Decision, MeetingReminder, Error, TodoMail, DecisionDocument, TodoState
 from views.forms import LoginForm, ProtocolTypeForm, DefaultTopForm, MeetingReminderForm, NewProtocolForm, DocumentUploadForm, KnownProtocolSourceUploadForm, NewProtocolSourceUploadForm, ProtocolForm, TopForm, SearchForm, NewProtocolFileUploadForm, NewTodoForm, TodoForm, TodoMailForm
 from views.tables import ProtocolsTable, ProtocolTypesTable, ProtocolTypeTable, DefaultTOPsTable, MeetingRemindersTable, ErrorsTable, TodosTable, DocumentsTable, DecisionsTable, TodoTable, ErrorTable, TodoMailsTable
 from legacy import import_old_todos
@@ -63,7 +63,10 @@ app.jinja_env.filters["timify"] = time_filter
 app.jinja_env.filters["datify_long"] = date_filter_long
 app.jinja_env.filters["url_complete"] = url_manager.complete
 app.jinja_env.filters["class"] = class_filter
+app.jinja_env.filters["todo_get_name"] = todostate_name_filter
+app.jinja_env.filters["code"] = code_filter
 app.jinja_env.tests["auth_valid"] = security_manager.check_user
+app.jinja_env.tests["needs_date"] = needs_date_test
 
 import tasks
 
@@ -126,7 +129,9 @@ def index():
 @app.route("/documentation")
 @login_required
 def documentation():
-    return render_template("documentation.html")
+    todostates = list(TodoState)
+    name_to_state = TodoState.get_name_to_state()
+    return render_template("documentation.html", todostates=todostates, name_to_state=name_to_state)
 
 @app.route("/types/list")
 @login_required
diff --git a/shared.py b/shared.py
index 1fca78b..c27e87f 100644
--- a/shared.py
+++ b/shared.py
@@ -76,9 +76,17 @@ def date_filter_short(date):
 def time_filter(time):
     return time.strftime("%H:%M")
 
+def needs_date_test(todostate):
+    return todostate.needs_date()
+def todostate_name_filter(todostate):
+    return todostate.get_name()
+
 def class_filter(obj):
     return obj.__class__.__name__
 
+def code_filter(text):
+    return "<code>{}</code>".format(text)
+
 from auth import LdapManager, SecurityManager, User
 ldap_manager = LdapManager(config.LDAP_PROVIDER_URL, config.LDAP_BASE)
 security_manager = SecurityManager(config.SECURITY_KEY)
diff --git a/templates/documentation.html b/templates/documentation.html
index a1d66e6..e4c8e85 100644
--- a/templates/documentation.html
+++ b/templates/documentation.html
@@ -24,7 +24,7 @@
         <ul>
             <li>Die ersten und letztes TOPs sind Standard-TOPs, die jede Sitzung hat. Die kannst du nur über beim Protokolltyp ändern, nicht beim Protokoll selbst.</li>
             <li>Die mittleren TOPs gehören nur zu dieser Sitzung. Du kannst welche hinzufügen oder sie umsortieren.</li>
-            <li>Solltest du die TOPs nicht bearbeiten können, handelt es sich um ein Protokoll, das du lesen, aber nicht bearbeiten kannst. Mehr dazu bei <a href="#Rechteverwaltung">Rechteverwaltung</a>.</li>
+            <li>Solltest du die TOPs nicht bearbeiten können, handelt es sich um ein Protokoll, das du lesen, aber nicht bearbeiten kannst. Mehr dazu bei <a href="#rechte">Rechteverwaltung</a>.</li>
         </ul>
         <h4 id="wie">Wie schreibe ich eine Protokoll?</h4>
         <ol>
@@ -35,10 +35,10 @@
             <li>falls Todo erledigt, markiere als erledigt (Details siehe <a href="#Todos">Todos</a></li>
             <li>schreibe das Protokoll im Etherpad</li>
             <li>Importiere das Protokoll am Ende mit „Aus Etherpad“</li>
-            <li>Falls Fehler auftreten, behebe sie (siehe <a href="#Fehler">Fehler</a></li>
+            <li>Falls Fehler auftreten, behebe sie (siehe <a href="#fehler">Fehler</a></li>
             <li>Wenn keine Fehler mehr auftreten, drucke das Protokoll mit „Löschen” (unten beim Anhang) aus.</li>
             <li>Korrekturlesen lassen und im Etherpad korrigieren, dann nochmal „aus Etherpad“</li>
-            <li>drucken, abheften und per Mail versenden</li>
+            <li>drucken, abheften, per Mail versenden und veröffentlichen</li>
         </ol>
         <h4 id="fehler">Was, wenn etwas nicht funktioniert?</h4>
         <ul>
@@ -52,7 +52,15 @@
             <li>Jedes Todo hat eine (oder durch Kommata oder Leerzeichen getrennt mehrere) Personen, die es erledigen sollen.</li>
             <li>Todos haben auch einen Zustand, in dem sie sich befinden. Es gibt:
                 <ul>
-                    {# todo: list states #}
+                    <li>offen: Das Todo muss noch erledigt werden</li>
+                    <li>wartet auf Rückmeldung: Jemand kümmert sich um das Todo, wartet allerdings gerade darauf, dass jemand anderes (intern oder extern) sich zurückmeldet.</li>
+                    <li>in Bearbeitung: Jemand kümmert sich gerade um das Todo.</li>
+                    <li>ab: Das Todo wird erst ab dem Datum relevant.</li>
+                    <li>vor: Das Todo muss vor dem Datum erledigt werden.</li>
+                    <li>verwaist: Das Todo hat niemanden, der es erledigen wird.</li>
+                    <li>erledigt: Das Todo ist erledigt.</li>
+                    <li>abgewiesen: Das Todo ist nicht und wird nicht mehr erledigt.</li>
+                    <li>obsolet: Das Todo wurde nicht erledigt und nun ist es zu spät, das noch zu tun.</li>
                 </ul>
             </li>
             <li>Alle Todos findest du unter <a href="{{url_for("list_todos")}}">Todos</a>.</li>
@@ -72,7 +80,12 @@
 
         Die öffentliche Version einsehen dürfen:
         <ul>
-            <li>Nicht authentifizierte Nutzer, wenn der Protokolltyp „Öffentlich“ eingestellt ist.</li>
+            <li>
+                Nicht authentifizierte Nutzer, wenn der Protokolltyp „Öffentlich“ eingestellt ist.
+                <ul>
+                    <li>Die Tagesordnung und Metadaten sind auch vor Veröffentlichung einsehbar.</li>
+                </ul>
+            </li>
             <li>Authentifizierte Nutzer auch dann, wenn es nicht „Öffentlich“ eingestellt ist, aber sie die „Öffentliche Gruppe“ oder die „Interne Gruppe” des Protokolltyps haben. Wenn keine Gruppe eingestellt ist, kann auch kein Nutzer diese haben.</li>
         </ul>
         Die interne Version einsehen dürfen:
@@ -127,7 +140,7 @@
 {% if config.PRIVATE_KEYWORDS|length > 0 %}
         <h4 id="intern">Interne Abschnitte</h4>
         Wenn der Name einer Liste (bis auf Leerzeichen und einen optionalen <code>:</code>) eins aus
-        <code>{{config.PRIVATE_KEYWORDS|join(" ")}}</code>
+        {{config.PRIVATE_KEYWORDS|map("code")|join(" ")|safe}}
         ist, ist diese Liste intern.
         Daher wird sie nur in der internen Version des Protokolls angezeigt.
 <pre>
@@ -160,6 +173,18 @@
 
         Ein bereits bestehender Todo wird mit der zusätzlichen Option <code>[…;id 1338]</code> in ein neues Protokoll eingefügt. Wird dieser Todo dann geändert, passiert das auch im Protokollsystem.
         Außerdem kann der Status des Todos, z.B. <code>[…;done;…]</code> angegeben werden.
+        Wenn der Status ein Datum benötigt 
+        ({{todostates|select("needs_date")|map("todo_get_name")|join(", ")}})
+        muss dies als <code>[…;dd.mm.yyyy;…]</code> angegeben werden.
+        <br>
+        Folgende Begriffe werden vom Protkollsystem verstanden (Groß- und Kleinschreibung spielt keine Rolle):
+        <ul>
+            {% for name in name_to_state %}
+                {% set state = name_to_state[name] %}
+                <li><code>{{name}}{% if state.needs_date() %};dd.mm.yyyy{% endif %}</code>: {{state.get_name()}}</li>
+            {% endfor %}
+        </ul>
+
 {% endif %}
     </div>
 </div>
diff --git a/todostates.py b/todostates.py
index baaf391..443ac00 100644
--- a/todostates.py
+++ b/todostates.py
@@ -29,6 +29,7 @@ def make_states(TodoState):
         "ab": TodoState.after,
         "erst ab": TodoState.after,
         "nicht vor": TodoState.after,
+        "wiedervorlage": TodoState.after,
         "after": TodoState.after,
         "not before": TodoState.after,
         "vor": TodoState.before,
-- 
GitLab