Commits

Ceasar Bautista  committed 8c090f6

Improve documentation

  • Participants
  • Parent commits d71876b

Comments (0)

Files changed (2)

 staticjinja
 ===========
 
-Script to easily deploy static sites using the jinja2 templating system.
+Script to easily deploy static sites using the jinja2 templating system.
+
+Requirements
+------------
+
+* jinja2 (`pip install jinja2`)
+* (optional, for automatic compilation) watchdog (`pip install watchdog`)
+
+Setup
+-----
+
+To compile the templates run `python build.py`. This will look execute the `main` function in `build.py` (which is set by default to build the `index.html` file inside of `./templates`).
+
+To compile additional pages, you will need to add more functions specifying how to compile each page. For pages which are loading any data, and therefore don't require a context, adding the line `build_template(env, 'mypage.html')` to `main` is sufficient. For pages which require a context of some sort, you will need to write a custom function that `main` calls, passing context data as extra arguments to `build_template`.
+
+Automatic Compilation
+---------------------
+
+If you installed `watchdog`, you can run 'python build.py --watch' to automatically recompile templates whenever a change is made.
 
 
 def build_template(env, template_name, **kwargs):
-    """Compile a template."""
+    """Compile a template.
+    *   env should be a Jinja environment variable indicating where to find the
+        templates.
+    *   template_name should be the name of the template as it appears inside
+        of `./templates`.
+    *   kwargs should be a series of key-value pairs. These items will be
+        passed to the template to be used as needed.
+    """
     print "Building %s..." % template_name
     template = env.get_template(template_name)
     with open(template_name, "w") as f:
 
 
 def parse_csv(filename):
-    """Read data from a CSV."""
+    """Read data from a CSV.
+    This will return a list of dictionaries, with key-value pairs corresponding
+    to each column in the parsed csv.
+    """
     with open(filename, 'rb') as f:
         return list(csv.DictReader(f))
 
 
-def build_index(env):
-    """Build the index page."""
-    build_template(env, 'index.html')
-
-
 def main():
+    """Compile each of the templates."""
     env = Environment(loader=FileSystemLoader(searchpath="./templates"))
-    build_index(env)
+
+    # Add any instructions to build templates here
+    build_template(env, 'index.html')
+
     print "Templates built."
+    return 0
 
 
 if __name__ == "__main__":