From 67b8c2301a15bfc35af147c3593dfbded8936851 Mon Sep 17 00:00:00 2001
From: Christian Kremitzl <christian.kremitzl@uni-bamberg.de>
Date: Tue, 17 Dec 2019 17:23:02 +0100
Subject: [PATCH] Commenting, formatting and slight refactoring.

---
 onpoint/__init__.py | 53 ++++++++++++++++++++++++++++++++-------------
 1 file changed, 38 insertions(+), 15 deletions(-)

diff --git a/onpoint/__init__.py b/onpoint/__init__.py
index e9cff5b..3106b91 100644
--- a/onpoint/__init__.py
+++ b/onpoint/__init__.py
@@ -1,9 +1,11 @@
-# Our python script goes here.
+#!/usr/bin/python3
 
 import yaml
 import pypandoc
 import re
 
+# Compiles a presentation in the given language from the given directory and
+# stores it in a corresponding slides.lang.html file inside the same directory.
 def compile(directory, language='en'):
     global root
     root = directory
@@ -16,6 +18,8 @@ def compile(directory, language='en'):
         output.write(wrapper)
     print('done')
 
+# Replaces the placeholders in the given content with corresponding values in 
+# the given language from the meta.yml and returns the filled content.
 def insert_metadata(content, lang=None):
     metadata = read_yaml('meta.yml')
     for key, value in metadata.items():
@@ -26,6 +30,8 @@ def insert_metadata(content, lang=None):
             content = content.replace(placeholder, filler)
     return content
 
+# Compiles a presentation's chapters (the content without the wrapper)
+# according to slides.yml and returns them as one string of <section>s.
 def compile_chapters():
     structure = read_yaml('slides.yml')
     chapters = ""
@@ -33,19 +39,24 @@ def compile_chapters():
         chapters += '<section>\n' + compile_chapter(chapter) + '\n</section>'
     return chapters # string
 
+# Compiles a presentation's chapter (given its name) by splitting it into
+# slides, compiling those, and returning them as a string of <article>s.
 def compile_chapter(chapter):
-    if type(chapter) == str: # plain chapter names
-        chapter_input = '\n' + open(root + 'slides/' + chapter + '.' + lang + '.md', 'r').read()
-        delimiter = '\n@slide'
-        slides = [delimiter + slide for slide in chapter_input.split(delimiter)][1:]
-        print(slides)
-        chapter = ''
-        for slide in slides:
-            chapter += '<article>\n' + compile_slide(slide) + '\n</article>\n'
-        return chapter # string
-    else:
-        raise Exception('Chapters with attributes are not supported yet.\n' + str(chapter))
+    if type(chapter) != str:
+        raise Exception('Chapters with attributes are not supported yet.\n' +
+                str(chapter))
+    chapter_file = open(root + 'slides/' + chapter + '.' + lang + '.md', 'r')
+    delimiter = '\n@slide'
+    chapter_input = ('\n' + chapter_file.read()).split(delimiter)
+    slides = [delimiter + slide for slide in chapter_input][1:]
+    chapter = ''
+    for slide in slides:
+        chapter += '<article>\n' + compile_slide(slide) + '\n</article>\n'
+    return chapter
 
+# Compiles a single slide by splitting it up into single metadata and data
+# attributes, loading them into the corresponding template, and returning the
+# result.
 def compile_slide(slide):
     slide = slide.strip()
     slide_metadata = get_slide_metadata(slide)
@@ -57,8 +68,11 @@ def compile_slide(slide):
         print('replace', placeholder, 'with', filler)
         if '@' + key in slide:
             slide = slide.replace(placeholder, filler)
-    return slide # string
+    return slide
 
+# Parses the metadata passage of a given slide and returns the metadata as a
+# dictionary. For some items, default values are used if the slide does not 
+# contain them.
 def get_slide_metadata(slide):
     metadata = { 'layout': 'default' }
     metadata_attributes = re.search('^@slide\((.+)\)', slide.splitlines()[0])
@@ -66,24 +80,32 @@ def get_slide_metadata(slide):
         metadata_attributes = metadata_attributes.group(1).split(' ')
         for attribute in metadata_attributes:
             metadata[attribute.split('=')[0]] = attribute.split('=')[1]
-    print("\nMETADATA:\n"+str(metadata)+"\n\n")
     return metadata
 
+# Parses the data part of a given slide and returns dictionary of field names
+# and corresponding raw values.
 def get_slide_data(slide):
     if slide.startswith('@slide'):
         slide = slide[slide.find('\n')+1:] # cut off @slide declaration
-    slide_data = { data.split()[0].strip('@') : "\n".join(data.splitlines()[1:]) for data in slide.strip().split('\n\n@') }
+    slide_data = slide.strip().split('\n\n@')
+    slide_data = { item.split()[0].strip('@') : "\n".join(item.splitlines()[1:]) for item in slide_data }
     return slide_data
 
+# Reads the layout file for a given layout name and returns its content as a
+# string.
 def get_slide_layout(layout_name):
     try:
         return open(root + 'layouts/' + layout_name + '.html', 'r').read()
     except FileNotFoundError:
         raise Exception('Layout ' + layout_name + ' not found!')
 
+# Calls the pandoc converter to convert a given Markdown string to HTML.
+# Returns an HTML string.
 def convert_slide_content(content):
     return pypandoc.convert_text(content, 'html', format='md')
 
+# Calls a YAML parser for the given relativ path inside the presentation root
+# directory. Returns a dictionary with the YAML content.
 def read_yaml(path):
     with open(root + path, 'r') as stream:
         try:
@@ -93,3 +115,4 @@ def read_yaml(path):
 
 compile('../test/', language='de')
 compile('../test/', language='en')
+