From 18df4d059e874a83f5c9c119a171a176fd60b7f7 Mon Sep 17 00:00:00 2001
From: Hartmut Seichter <hartmut@gmail.com>
Date: Sun, 19 May 2024 14:03:41 +0200
Subject: [PATCH] first run of a documentation to describe the use of the
 various fields

---
 coursebuilder/docs/quickstart.md | 41 ++++++++++++++++++++++++++++++++
 coursebuilder/schema.py          | 23 ++++++++++++------
 2 files changed, 57 insertions(+), 7 deletions(-)
 create mode 100644 coursebuilder/docs/quickstart.md

diff --git a/coursebuilder/docs/quickstart.md b/coursebuilder/docs/quickstart.md
new file mode 100644
index 0000000..a293ef4
--- /dev/null
+++ b/coursebuilder/docs/quickstart.md
@@ -0,0 +1,41 @@
+# Concept
+
+The concept behind coursebuilder is to store curricula descriptions in `YAML` files that can be versioned in a git repository. Unlike classic databases an observable and well defined versioning is paramount in these descriptions as they are the legal foundation for study and exam regulations.
+
+The following pieces play together here:
+
+- `schema` files, usually a `schema.yaml`
+- `mod` files, usually something along the lines of `mod.coursecode.yaml` 
+- `book` files describing a whole regulation set and course global details
+- some sort of transformation with `coursebuilder` into Markdown that is piped through [pandoc](https://pandoc.org) in order to generate PDF, HTML and other representation from this code 
+
+# schema files 
+
+Schema files are responsible to describe the used structures in a database. The following datatypes are supported:
+
+- `str` a simple string, can be accompanied with a `template`
+- `enum` a classic enum datatype with a fixed set of values
+- `num` a numeric datatype 
+- `multinum` an array type with the possibility to `spec` each value
+- `multikey` a key-value type with additional numeric data associated with each key instance  
+
+# mod files (modules)
+
+Modules describe a course in detail and implement an instance of the schema file. Especially `strings` and `enums` are translatable One of the plan is to use a validator to find inconsistencies automatically, like workloads that are not following the 30h = 1ECTS rule.
+
+
+# datatypes
+
+## `str` datatype
+
+```yaml
+# this would reside in a schema field on top level
+# a field of name 'id'
+id: # name of the field 
+    type: str # sets the datatype to str
+    translatable: false # enforces the value is not translatable (default is true)
+    label: { # label describes the meaning of the datatype in regards of the schema
+        de: "Kürzel",   # translation of the label in German (de)
+        en: "code" # translation of the label in English (en)
+    }
+```
\ No newline at end of file
diff --git a/coursebuilder/schema.py b/coursebuilder/schema.py
index a81fda7..0f7612e 100644
--- a/coursebuilder/schema.py
+++ b/coursebuilder/schema.py
@@ -8,11 +8,11 @@ class Schema:
     def keys(self):
         return self.__schema.keys()
 
-    def get_template(self,field,lang='de'):
-        if 'template' in self.__schema[field]:
-            return self.__schema[field]['template'][lang]
-        else:
-            return "$value"        
+    # def get_template(self,field,lang='de'):
+    #     if 'template' in self.__schema[field]:
+    #         return self.__schema[field]['template'][lang]
+    #     else:
+    #         return "$value"        
         
     def is_translatable(self,field):
         if 'translatable' in self.__schema[field]:
@@ -114,14 +114,20 @@ class Schema:
     #     return table_items
     
     def get_value(self,meta,field,lang):
-        """treats receiving the value like a variant, 
-           return values are language specific"""
+        """
+        treats receiving the value like a variant, 
+        returns values with their language specific representations
+        """
         match self.__schema[field]['type']: 
             case 'str': return meta[field][lang] if self.is_translatable(field) else meta[field]['value']
             case 'enum' | 'int' | 'num' | 'multikey' : return meta[field]['value']
             case 'multinum': return meta[field]['value'] if hasattr(meta[field]['value'],'__iter__') else (meta[field]['value'],) # force list!
     
     def to_list_of_dict(self,meta,fields,lang):
+        """
+        generates a list of dict which can easily be converted 
+        to a pandas dataframe
+        """
         # list comprehension for rows
         return [{'field' : field,   # field name
                   'lang' : lang,    # language shortcode
@@ -139,6 +145,9 @@ class Schema:
     def to_list_of_tuple(self,meta,fields,lang):
         """
         generates a list of tuples with a label and value (text)
+        this is usually consumed by a Markdown generator
+
+        todo: needs deuglyfication of free standing loop, templates are possible for all
         """
         list = []
         for r in self.to_list_of_dict(meta,fields,lang):