added templates doc and improved configuration doc

doc/configuration.md

@@ -1,42 +1,57 @@
 # Configuration
 
-Appier can be configured through environment variables. The following would configure the logger to print only messages whose level is "critical" or above:
+Appier can be configured through environment variables. The following would configure the 
+logger to print only messages whose level is "critical" or above:
 
 ```bash
 LEVEL=INFO python hello_world.py
 ```
 
-The following are all the available configuration variables:
+The following are all the available settings:
 
 * `LEVEL` (`str`) - Defines the level of verbodity for the loggers (eg: `DEBUG`)
-* `FILE_LOG` (`bool`) - Enables the rotating file based logging (eg: `/var/log/name.log`, `/var/log/name.err`)
-* `LOGGING` (`list`) - Defines a sequence of logging handlers configuration to be loaded (eg: 'complex' example project)
+* `FILE_LOG` (`bool`) - Enables the rotating file based logging (eg: `/var/log/name.log`, 
+`/var/log/name.err`)
+* `LOGGING` (`list`) - Defines a sequence of logging handlers configuration to be loaded 
+(eg: 'complex' example project)
 * `SERVER` (`str`) - The server that will host the app (eg: `netius`)
 * `SMTP_HOST` (`str`) - The host where an SMTP server is running.
 * `SMTP_PORT` (`int`) - The port where an SMTP server is listening (default: 25).
 * `SMTP_USER` (`str`) - The username used to authenticate with the SMTP server.
 * `SMTP_PASSWORD` (`str`) - The password used to authenticate with the SMTP server.
-* `SMTP_STARTTLS` (`bool`) - Flag used to tell the server that the client supports Transport Layer Security (default: True).
+* `SMTP_STARTTLS` (`bool`) - Flag used to tell the server that the client supports Transport 
+Layer Security (default: True).
 
-The configuration can also be provided by creating an `appier.json` in the root of your project directory:
+The configuration can also be provided by creating an `appier.json` file in the root of your 
+project directory:
 
 ```json
 {
     "LEVEL" : "WARNING"
 }
 ```
 
-You can also create a configuration file in your home directory, also named `appier.json`:
+You can also create an environment configuration file in your home directory, also 
+named `appier.json`. Command line configurations will override project level 
+configurations, which will in turn override environment (home directory) configurations. 
+
+To retrieve configuration values from anywhere in the app do:
 
 ```json
-{
-    "LEVEL" : "CRITICAL"
-}
+level = appier.conf("LEVEL")
+```
+
+You can also provide a default, so the app still works when that setting is missing:
+
+```json
+level = appier.conf("LEVEL", "INFO")
 ```
 
 ### Web server
 
-Appier uses the wsgiref web server that comes with the Python standard library by default. You can easily swap it out with a better server like the one provided in [Netius](http://netius.hive.pt) by doing:
+Appier uses the wsgiref web server that comes with the Python standard library by default. 
+You can easily swap it out with a better server like the one provided in 
+[Netius](http://netius.hive.pt) by doing:
 
 ```
 pip install netius

doc/templates.md

@@ -0,0 +1,61 @@
+# Templates
+
+Templates in Appier are rendered using [Jinja](http://jinja.pocoo.org/). Therefore,
+how to create them is best learned from its website
+
+At the moment, the only detail specific to Appier that is worth noticing, is on how
+to resolve URLs. Appier is object-oriented, which amongst other things, allows you 
+to have multiple route handlers with the same name, as long as they're in different 
+controllers. To render an hyperlink for an handler named ``list_cats`` that is in the
+``CatController``, you would do the following:
+
+```html
+<a href="{{ url_for('cat.list_cats') }}>List Cats</a>
+```
+
+With the syntax explained, all you need to know know is how to render a template
+and return it as a response to a request. Here's the handler for the previous example:
+
+```python
+import appier
+
+class CatController(appier.Controller):
+
+    @appier.route("/cats", "GET")
+    def list_cats(self):
+        return self.template(
+            "cats/list.html.tpl"
+        )
+```
+
+The ``list_cats`` handler in this example would render the template in 
+``templates/cats/list.html.tpl`` and return it as a response. To make this example more
+complete, we would need to retrieve the cats and use them in the template:
+
+```python
+import appier
+
+import models
+
+class CatController(appier.Controller):
+
+    @appier.route("/cats", "GET")
+    def list_cats(self):
+    	cats = models.Cat.find()
+        return self.template(
+            "cats/list.html.tpl",
+            cats = cats
+        )
+```
+
+Any keyword arguments passed to the ``template`` method become available in the template:
+
+```html
+<table>
+    {% for cat in cats %}
+    	<tr>
+    		<td>{{ cat.name }}</td>
+    	</tr>
+    {% endfor %}
+</table>
+```

readme.md

@@ -52,6 +52,7 @@ For the purposes of rapid web development, Appier goes well with [Netius](http:/
 * [Internationalization](doc/i18n.md)
 * [Logging](doc/logging.md)
 * [Email](doc/email.md)
+* [Templates](doc/templates.md)
 
 More information can be found in the [Advanced Topics](doc/advanced.md) page.