Browse files

Moved Renderer docs into README, so all docs are in one place

  • Loading branch information...
1 parent 679993e commit 06397ab739d475f21511318d2cd320fb229d6a7a @benhoyt committed Oct 8, 2012
Showing with 26 additions and 23 deletions.
  1. +21 −1
  2. +5 −22
@@ -392,7 +392,27 @@ a couple of dict lookups.
Customizing Renderer
+To customize rendering settings, simply pass arguments to the `Renderer()`
+initializer as follows:
+* **template_dir** is the only required argument -- it specifies the root
+directory of your Symplate source files.
+* **output_dir** is the directory the compiled Python template files will go
+into. The default is `symplouts` at the same level as your `template_dir`.
+* **extension** is the file extension for templates. The default is `'.symp'`.
+Set this to `''` if you want to specify the file extension explicitly when
+calling render.
+* **check_mtimes** is off by default. Set to True to tell Symplate to check
+the template files' modify times on render, which is slower and usually only
+used for debugging.
+* **modify_path** is on by default, and means Symplate will put
+`output_dir/..` first on `sys.path` so it can import compiled templates. Set
+to False if you want to manage this manually.
+* **preamble** defaults to empty string, and specifies extra code to include
+at the top of all compiled template. Useful for imports you use in many
+* **default_filter** defaults to `'symplate.html_filter'`, and is used to
+[override the default filter](#overriding-the-default-filter).
Unicode handling
@@ -14,7 +14,7 @@
def html_filter(s):
"""Escape special HTML/XML characters in given ASCII or unicode string
- (this is the default output filter in templates).
+ (the default output filter in templates).
# slight performance boost by feeding correct string type into replace()
if isinstance(s, unicode):
@@ -53,31 +53,14 @@ def __repr__(self):
class Renderer(object):
- """Symplate renderer class. See __init__'s docs for more info."""
+ """Symplate renderer class. Holds settings for rendering and caches
+ compiled template modules.
+ """
def __init__(self, template_dir, output_dir=None, extension='.symp',
check_mtimes=False, modify_path=True, preamble='',
- """Initialize a Renderer instance.
- * template_dir: directory your Symplate source files are in (the
- only required argument)
- * output_dir: directory compiled template (.py) files should go
- into, default is {template_dir}/../symplouts
- * extension: file extension for templates (set to '' if you want
- to specify explictly when calling render)
- * check_mtimes: True means check template file's mtime on render(),
- which is slower and usually only used for debugging
- * modify_path: True means add output_dir/.. to sys.path for
- importing compiled template
- * preamble: extra code to include at top of compiled template,
- such as imports
- * default_filter: if a string, use directly as Python expression for
- default filter; otherwise this must be a function
- that takes a single filename argument (e.g., if you
- want to use the file extension to determine the
- default filter)
- """
+ """Initialize a Renderer instance. See for more info."""
self.template_dir = os.path.abspath(template_dir)
if output_dir is None:
output_dir = os.path.abspath(os.path.join(self.template_dir, '..',

0 comments on commit 06397ab

Please sign in to comment.