Commits

Andriy Kornatskyy  committed ad3a178

Updated documentation per integration with Tenjin templates.

  • Participants
  • Parent commits 28059d2

Comments (0)

Files changed (6)

 (MVC) architectural pattern (push-based) to separate the data model from
 the user interface.
 
+The framework is template engine agnostic and provides integration with
+the following template systems:
+
+* `Mako Templates <http://www.makotemplates.org>`_
+* `Tenjin Templates <http://www.kuwata-lab.com/tenjin/>`_
+
 It is optimized for performance, well tested and documented.
 
 Resources:
 .. _`source code`: http://bitbucket.org/akorn/wheezy.web/src
 .. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
 .. _`wheezy.web`: http://pypi.python.org/pypi/wheezy.web
-.. _`WSGI`: http://www.python.org/dev/peps/pep-3333

File doc/examples.rst

 let setup `virtualenv`_ environment::
 
     $ virtualenv env
-    $ env/bin/easy_install wheezy.web
 
-.. _helloworld:
+Since :ref:`wheezy.web` is template engine agnostic, you need specify
+extra requirements (per template engine of your choice)::
+
+    $ env/bin/easy_install wheezy.web[mako]
+
+or::
+
+    $ env/bin/easy_install wheezy.web[tenjin]
+
+Templates
+---------
+
+`Template`_ application serves template purpose for you. It includes:
+
+* Integration with both mako and tenjin template system.
+* User registration and authentication.
+* Form validation.
+
+If you are about to start a new project it is a good starting point.
 
 Hello World
 -----------
     ----------------------------------------------------------------------
     Ran 1 test in 3.686s
 
-.. _public_demo:
-
-Public
-------
-
-`Public`_ application serves template purpose for you. If you are about to start a
-new project it is a good starting point.
 
 .. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
 .. _`hello.py`: https://bitbucket.org/akorn/wheezy.web/src/tip/demos/hello/hello.py
 .. _`test_hello.py`: https://bitbucket.org/akorn/wheezy.web/src/tip/demos/hello/test_hello.py
 .. _`benchmark_hello.py`: https://bitbucket.org/akorn/wheezy.web/src/tip/demos/hello/benchmark_hello.py
-.. _`public`: https://bitbucket.org/akorn/wheezy.web/src/tip/demos/public
+.. _`template`: https://bitbucket.org/akorn/wheezy.web/src/tip/demos/template
 .. _`WSGI`: http://www.python.org/dev/peps/pep-3333
 .. _`wheezy.http`: http://packages.python.org/wheezy.http
 .. _`wheezy.routing`: http://packages.python.org/wheezy.routing
+

File doc/gettingstarted.rst

 -------
 
 :ref:`wheezy.web` requires `python`_ version 2.4 to 2.7 or 3.2.
-It is independent of operating system. You can install it from `pypi`_ 
+It is independent of operating system. You can install it from `pypi`_
 site using `setuptools`_::
 
     $ easy_install wheezy.web
-    
+
 If you are using `virtualenv`_::
 
     $ virtualenv env
     $ env/bin/easy_install wheezy.web
 
+Since :ref:`wheezy.web` is template engine agnostic, you need specify
+extra requirements (per template engine of your choice)::
+
+    $ env/bin/easy_install wheezy.web[mako]
+    $ env/bin/easy_install wheezy.web[tenjin]
+
 Develop
 -------
 
 
     $ make test
 
-You can read how to compile from source code different versions of 
+You can read how to compile from source code different versions of
 `python`_ in the `article`_ published on `mind reference`_ blog.
 
 You can run certain make targets with specific python version. Here
 we are going to run `doctest`_ with python3.2::
 
     $ make env doctest-cover VERSION=3.2
-    
+
 Generate documentation with `sphinx`_::
 
 	$ make doc
 If you run into any issue or have comments, go ahead and add on
 `bitbucket`_.
 
+.. _`article`: http://mindref.blogspot.com/2011/09/compile-python-from-source.html
+.. _`bitbucket`: http://bitbucket.org/akorn/wheezy.web/issues
+.. _`doctest`: http://docs.python.org/library/doctest.html
+.. _`mercurial`: http://mercurial.selenic.com/
+.. _`mind reference`: http://mindref.blogspot.com/
 .. _`pypi`: http://pypi.python.org/pypi/wheezy.web
 .. _`python`: http://www.python.org
 .. _`setuptools`: http://pypi.python.org/pypi/setuptools
-.. _`bitbucket`: http://bitbucket.org/akorn/wheezy.web/issues
 .. _`source code`: http://bitbucket.org/akorn/wheezy.web/src
-.. _`mercurial`: http://mercurial.selenic.com/
+.. _`sphinx`: http://sphinx.pocoo.org/
 .. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
-.. _`article`: http://mindref.blogspot.com/2011/09/compile-python-from-source.html
-.. _`mind reference`: http://mindref.blogspot.com/
-.. _`doctest`: http://docs.python.org/library/doctest.html
-.. _`sphinx`: http://sphinx.pocoo.org/
+

File doc/index.rst

 :ref:`wheezy.web` is a `python`_ package written in pure Python code.
 It is a lightweight `WSGI`_ web framework.
 
+The framework is template engine agnostic and provides integration with
+the following template systems:
+
+* `Mako Templates <http://www.makotemplates.org>`_
+* `Tenjin Templates <http://www.kuwata-lab.com/tenjin/>`_
+
 It is optimized for performance, well tested and documented.
 
 Resources:

File doc/tutorial.rst

 .. _`wheezy.html`: http://packages.python.org/wheezy.html
 .. _`wheezy.http`: http://packages.python.org/wheezy.http
 .. _`wheezy.validation`: http://packages.python.org/wheezy.validation
-.. _`jQuery`: http://docs.jquery.com/Downloading_jQuery
+.. _`jquery`: http://jquery.com/

File doc/userguide.rst

   implementation return ``NullTranslations`` object. Your application handler
   must override this attribute to provide valid ``gettext`` translations.
 
-Here is example from :ref:`public_demo` demo application::
+Here is example from `template`_ demo application::
 
     class SignInHandler(BaseHandler):
 
 * ``ValidationMixin::error(message)`` - adds a general error (this error
   is added with key *__ERROR__*).
 
-Here is example from :ref:`public_demo` demo application (see file
+Here is example from `template`_ demo application (see file
 `membership/web/views.py`_)::
 
     class SignInHandler(BaseHandler):
 submitted. In case ``try_update_model`` or ``valida`` fails we re-display
 sign in page with errors reported.
 
-Here is example from :ref:`public_demo` demo application that demonstrates
+Here is example from `template`_ demo application that demonstrates
 how to use general error (see file `membership/web/views.py`_)::
 
     class SignUpHandler(BaseHandler):
 
 Please note that `wheezy.html`_ package provides optimization of widgets
 per template engine used. That optimization is provided through use of
-template specific constructs. Preprocessor for Mako templates translates
-widgets to Mako operations offering optimal performance. If you are
-using template engine with preprocessing you can eliminate need to wrap
-widgets explicitely in your handler (since all calls to widgets in template
-are  replaced with appropriate template native constructs).
+template specific constructs. Preprocessor for Mako/Tenjin templates
+translates widgets to template engine specific operations offering optimal
+performance.
+
+If you are using template engine with preprocessing you can eliminate need
+to wrap widgets explicitely in your handler (since all calls to widgets
+in template are replaced with appropriate template native constructs).
 
 Read more about available widgets in `wheezy.html`_ package.
 
 a dictionary that extends ``options`` with the following information: errors,
 locale, principal and translations.
 
-Here is example from :ref:`public_demo` demo application (see
+Here is example from `template`_ demo application (see
 `membership/web/views.py`_)::
 
     class SignInHandler(BaseHandler):
 together with ``gzip_transform`` and ``response_cache`` (requries HTTP cache
 middleware).
 
-Here is example from :ref:`public_demo` demo application::
+Here is example from `template`_ demo application::
 
     from wheezy.http import response_cache
     from wheezy.http.transforms import gzip_transform
 :ref:`wheezy.web` does not provide own implementation for template rendering
 instead it offers integration with the following packages:
 
-* Mako Templates
+* `Mako`_ Templates
+* `Tenjin`_ Templates
+
+Contract
+~~~~~~~~
+
+Template contract is any callable of the following form::
+
+    def render_template(self, template_name, **kwargs):
+        return 'unicode string'
 
 Mako Templates
 ~~~~~~~~~~~~~~
 Here is configuration option to define how templates are rendered within
 application (see `config.py`_ for details)::
 
-    options = {}
-    options['render_template'] = MakoTemplate(
+    from wheezy.html.ext.mako import whitespace_preprocessor
+    from wheezy.html.ext.mako import widget_preprocessor
+    from wheezy.web.templates import MakoTemplate
+
+
+    render_template = MakoTemplate(
+            module_directory='/tmp/mako_modules',
+            filesystem_checks=False,
             directories=['content/templates'],
-            filesystem_checks=False,
-            template_cache=template_cache),
+            cache_factory=cache_factory,
+            preprocessor=[
+                widget_preprocessor,
+                whitespace_preprocessor,
+            ])
 
 The arguments passed to ``MakoTemplate`` are specific to Mako templates and
 not explained here. Please refer to `Mako`_ documentation.
 
-Contract
-~~~~~~~~
+Tenjin Templates
+~~~~~~~~~~~~~~~~
 
-Template contract is any callable of the following form::
+Here is configuration option to define how templates are rendered within
+application (see `config.py`_ for details)::
 
-    def render_template(self, template_name, **kwargs):
-        return string
+    from wheezy.html.ext.tenjin import whitespace_preprocessor
+    from wheezy.html.ext.tenjin import widget_preprocessor
+    from wheezy.html.utils import format_value
+    from wheezy.web.templates import TenjinTemplate
+
+    render_template = TenjinTemplate(
+            path=['content/templates'],
+            pp=[
+                widget_preprocessor,
+                whitespace_preprocessor,
+            ],
+            helpers={
+                'format_value': format_value
+            })
+
+The arguments passed to ``TenjinTemplate`` are specific to Tenjin templates
+and not explained here. Please refer to `Tenjin`_ documentation.
 
 Caching
 -------
 Please refer to `wheezy.http`_ documentation for more information. All features
 available in `wheezy.http`_ caching are applicable.
 
+Content caching plus cache dependency is the most advanced boost of your
+application performance. Regardless of template engine this can give up to
+8-10 times better performance.
 
-
-.. _`WSGI`: http://www.python.org/dev/peps/pep-3333
+.. _`config.py`: https://bitbucket.org/akorn/wheezy.web/src/tip/demos/template/src/config.py
+.. _`core.js`: https://bitbucket.org/akorn/wheezy.web/src/tip/demos/template/content/static/js/core.js
+.. _`i18n`: https://bitbucket.org/akorn/wheezy.web/src/tip/demos/template/i18n
+.. _`mako`: http://docs.makotemplates.org
+.. _`membership/web/views.py`: https://bitbucket.org/akorn/wheezy.web/src/tip/demos/template/src/membership/web/views.py
+.. _`template`: https://bitbucket.org/akorn/wheezy.web/src/tip/demos/template
+.. _`tenjin`: http://www.kuwata-lab.com/tenjin
 .. _`wheezy.core`: http://bitbucket.org/akorn/wheezy.core
 .. _`wheezy.html`: http://packages.python.org/wheezy.html
 .. _`wheezy.http`: http://packages.python.org/wheezy.http
 .. _`wheezy.routing`: http://packages.python.org/wheezy.routing
+.. _`wheezy.security`: http://packages.python.org/wheezy.security
 .. _`wheezy.validation`: http://packages.python.org/wheezy.validation
-.. _`wheezy.security`: http://packages.python.org/wheezy.security
-.. _`i18n`: https://bitbucket.org/akorn/wheezy.web/src/tip/demos/public/i18n
-.. _`config.py`: https://bitbucket.org/akorn/wheezy.web/src/tip/demos/public/src/config.py
-.. _`membership/web/views.py`: https://bitbucket.org/akorn/wheezy.web/src/tip/demos/public/src/membership/web/views.py
-.. _`core.js`: https://bitbucket.org/akorn/wheezy.web/src/tip/demos/public/content/static/js/core.js
-.. _`mako`: http://docs.makotemplates.org
+.. _`WSGI`: http://www.python.org/dev/peps/pep-3333