Permalink
Browse files

first version of the jinja2 docs

--HG--
branch : trunk
  • Loading branch information...
1 parent d134231 commit 3c8b7ade4a8fed525154db87be6f9bbdceac1f6a @mitsuhiko mitsuhiko committed Apr 28, 2008
View
No changes.
View
No changes.
View
No changes.
View
@@ -0,0 +1,191 @@
+API
+===
+
+.. module:: jinja2
+ :synopsis: public Jinja2 API
+
+This document describes the API to Jinja2 and not the template language. It
+will be most useful as reference to those implementing the template interface
+to the application and not those who are creating Jinja2 templates.
+
+Basics
+------
+
+Jinja2 uses a central object called the template :class:`Environment`.
+Instances of this class are used to store the configuration, global objects
+and are used to load templates from the file system or other locations.
+Even if you are creating templates from string by using the constructor of
+:class:`Template` class, an environment is created automatically for you.
+
+Most applications will create one :class:`Environment` object on application
+initialization and use that to load templates. In some cases it's however
+useful to have multiple environments side by side, if different configurations
+are in use.
+
+The simplest way to configure Jinja2 to load templates for your application
+looks roughly like this::
+
+ from jinja2 import Environment, PackageLoader
+ env = Environment(loader=PackageLoader('yourapplication', 'templates'))
+
+This will create a template environment with the default settings and a
+loader that looks up the templates in the `templates` folder inside the
+`yourapplication` python package. Different loaders are available
+and you can also write your own if you want to load templates from a
+database or other resources.
+
+To load a template from this environment you just have to call the
+:meth:`get_template` method which then returns the loaded :class:`Template`::
+
+ template = env.get_template('mytemplate.html')
+
+To render it with some variables, just call the :meth:`render` method::
+
+ print template.render(the='variables', go='here')
+
+
+High Level API
+--------------
+
+.. autoclass:: jinja2.environment.Environment
+ :members: from_string, get_template, join_path
+
+ .. attribute:: shared
+
+ If a template was created by using the :class:`Template` constructor
+ an environment is created automatically. These environments are
+ created as shared environments which means that multiple templates
+ may have the same anonymous environment. For all shared environments
+ this attribute is `True`, else `False`.
+
+ .. attribute:: sandboxed
+
+ If the environment is sandboxed this attribute is `True`. For the
+ sandbox mode have a look at the documentation for the
+ :class:`~jinja2.sandbox.SandboxedEnvironment`.
+
+ .. attribute:: filters
+
+ A dict of filters for this environment. As long as no template was
+ loaded it's safe to add new filters or remove old.
+
+ .. attribute:: tests
+
+ A dict of test funcitons for this environment. As long as no
+ template way loaded it's safe to modify this dict.
+
+ .. attribute:: globals
+
+ A dict of global variables. These variables are always available
+ in a template and (if the optimizer is enabled) may not be
+ override by templates. As long as no template was loaded it's safe
+ to modify this dict.
+
+
+.. autoclass:: jinja2.Template
+ :members: render, stream, generate, include
+
+
+.. autoclass:: jinja2.environment.TemplateStream
+ :members: disable_buffering, enable_buffering
+
+
+Undefined Types
+---------------
+
+These classes can be used as undefined types. The :class:`Environment`
+constructor takes an `undefined` parameter that can be one of those classes
+or a custom subclass of :class:`Undefined`. Whenever the template engine is
+unable to look up a name or access an attribute one of those objects is
+created and returned. Some operations on undefined values are then allowed,
+others fail.
+
+The closest to regular Python behavior is the `StrictUndefined` which
+disallows all operations beside testing if it's an undefined object.
+
+.. autoclass:: jinja2.runtime.Undefined
+
+.. autoclass:: jinja2.runtime.DebugUndefined
+
+.. autoclass:: jinja2.runtime.StrictUndefined
+
+
+Loaders
+-------
+
+Loaders are responsible for loading templates from a resource such as the
+file system and for keeping the compiled modules in memory. These work like
+Python's `sys.modules` which keeps the imported templates in memory. Unlike
+`sys.modules` however this cache is limited in size by default and templates
+are automatically reloaded. Each loader that extends :class:`BaseLoader`
+supports this caching and accepts two parameters to configure it:
+
+`cache_size`
+ The size of the cache. Per default this is ``50`` which means that if
+ more than 50 templates are loaded the loader will clean out the least
+ recently used template. If the cache size is set to ``0`` templates are
+ recompiled all the time, if the cache size is ``-1`` the cache will not
+ be cleaned.
+
+`auto_reload`
+ Some loaders load templates from locations where the template sources
+ may change (ie: file system or database). If `auto_reload` is set to
+ `True` (default) every time a template is requested the loader checks
+ if the source changed and if yes, it will reload the template. For
+ higher performance it's possible to disable that.
+
+.. autoclass:: jinja2.loaders.FileSystemLoader
+
+.. autoclass:: jinja2.loaders.PackageLoader
+
+.. autoclass:: jinja2.loaders.DictLoader
+
+.. autoclass:: jinja2.loaders.FunctionLoader
+
+.. autoclass:: jinja2.loaders.PrefixLoader
+
+.. autoclass:: jinja2.loaders.ChoiceLoader
+
+All loaders are subclasses of :class:`BaseLoader`. If you want to create your
+own loader, subclass :class:`BaseLoader` and override `get_source`.
+
+.. autoclass:: jinja2.loaders.BaseLoader
+ :members: get_source, load
+
+
+Utilities
+---------
+
+These helper functions and classes are useful if you add custom filters or
+functions to a Jinja2 environment.
+
+.. autofunction:: jinja2.filters.environmentfilter
+
+.. autofunction:: jinja2.filters.contextfilter
+
+.. autofunction:: jinja2.utils.environmentfunction
+
+.. autofunction:: jinja2.utils.contextfunction
+
+.. function:: escape(s)
+
+ Convert the characters &, <, >, and " in string s to HTML-safe sequences.
+ Use this if you need to display text that might contain such characters
+ in HTML. This function will not escaped objects that do have an HTML
+ representation such as already escaped data.
+
+.. autoclass:: jinja2.utils.Markup
+
+
+Exceptions
+----------
+
+.. autoclass:: jinja2.exceptions.TemplateError
+
+.. autoclass:: jinja2.exceptions.UndefinedError
+
+.. autoclass:: jinja2.exceptions.TemplateNotFound
+
+.. autoclass:: jinja2.exceptions.TemplateSyntaxError
+
+.. autoclass:: jinja2.exceptions.TemplateAssertionError
View
@@ -16,14 +16,14 @@
# If your extensions are in another directory, add it here. If the directory
# is relative to the documentation root, use os.path.abspath to make it
# absolute, like shown here.
-#sys.path.append(os.path.abspath('some/directory'))
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
# General configuration
# ---------------------
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc']
+extensions = ['sphinx.ext.autodoc', 'jinjaext']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
View
@@ -0,0 +1,60 @@
+Introduction
+============
+
+This is the documentation for the Jinja2 general purpose templating language.
+Jinja2 is a library for Python 2.4 and onwards that is designed to be flexible,
+fast and secure.
+
+If you have any exposure to other text-based template languages, such as Smarty or
+Django, you should feel right at home with Jinja2. It's both designer and
+developer friendly by sticking to Python's principles and adding functionality
+useful for templating environments.
+
+The key-features are...
+
+- ... **configurable syntax**. If you are generating LaTeX or other formats
+ with Jinja you can change the delimiters to something that integrates better
+ into the LaTeX markup.
+
+- ... **fast**. While performance is not the primarily target of Jinja2 it's
+ surprisingly fast. The overhead compared to regular Python code was reduced
+ to the very minimum.
+
+- ... **easy to debug**. Jinja2 integrates directly into the python traceback
+ system which allows you to debug Jinja templates with regular python
+ debugging helpers.
+
+- ... **secure**. It's possible to evaluate untrusted template code if the
+ optional sandbox is enabled. This allows Jinja2 to be used as templating
+ language for applications where users may modify the template design.
+
+
+Prerequisites
+-------------
+
+Jinja2 needs at least **Python 2.4** to run. Additionally a working C-compiler
+that can create python extensions should be installed for the debugger. If no
+C-compiler is available the `ctypes`_ module should be installed.
+
+.. _ctypes: http://python.net/crew/theller/ctypes/
+
+
+Basic API Usage
+---------------
+
+This section gives you a brief introduction to the Python API for Jinja templates.
+
+The most basic way to create a template and render it is through
+:class:`Template`. This however is not the recommended way to work with it,
+but the easiest
+
+>>> from jinja2 import Template
+>>> template = Template('Hello {{ name }}!')
+>>> template.render(name='John Doe')
+u'Hello John Doe!'
+
+By creating an instance of :class:`Template` you get back a new template
+object that provides a method called :meth:`~Template.render` which when
+called with a dict or keyword arguments expands the template. The dict
+or keywords arguments passed to the template are the so-called "context"
+of the template.
View
@@ -0,0 +1,66 @@
+# -*- coding: utf-8 -*-
+"""
+ Jinja Documentation Extensions
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ Support for automatically documenting filters and tests.
+
+ :copyright: Copyright 2008 by Armin Ronacher.
+ :license: BSD.
+"""
+import inspect
+from docutils import nodes
+from docutils.statemachine import ViewList
+from sphinx.ext.autodoc import prepare_docstring
+
+
+def format_filter(name, aliases, func):
+ try:
+ argspec = inspect.getargspec(func)
+ except:
+ try:
+ argspec = inspect.getargspec(func.__init__)
+ except:
+ try:
+ argspec = inspect.getargspec(func.__new__)
+ except:
+ return []
+ del argspec[0][0]
+ if getattr(func, 'environmentfilter', False) or \
+ getattr(func, 'contextfilter', False):
+ del argspec[0][0]
+ signature = inspect.formatargspec(*argspec)
+ result = ['.. function:: %s%s' % (name, signature), '']
+ for line in inspect.getdoc(func).splitlines():
+ result.append(' ' + line)
+ if aliases:
+ result.extend(('', ' :aliases: %s' % ', '.join(
+ '``%s``' % x for x in sorted(aliases))))
+ return result
+
+
+def jinja_filters(dirname, arguments, options, content, lineno,
+ content_offset, block_text, state, state_machine):
+ from jinja2.defaults import DEFAULT_FILTERS
+ mapping = {}
+ for name, func in DEFAULT_FILTERS.iteritems():
+ mapping.setdefault(func, []).append(name)
+ filters = []
+ for func, names in mapping.iteritems():
+ aliases = sorted(names, key=lambda x: len(x))
+ name = aliases.pop()
+ filters.append((name, aliases, func))
+ filters.sort()
+
+ result = ViewList()
+ for name, aliases, func in filters:
+ for item in format_filter(name, aliases, func):
+ result.append(item, '<jinjaext>')
+
+ node = nodes.paragraph()
+ state.nested_parse(result, content_offset, node)
+ return node.children
+
+
+def setup(app):
+ app.add_directive('jinjafilters', jinja_filters, 1, (0, 0, 0))
Oops, something went wrong.

0 comments on commit 3c8b7ad

Please sign in to comment.