From 015b0c9437fa37cce4eeb44ed7a7311bbd592b85 Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Sun, 11 Nov 2007 00:10:17 +0100 Subject: [PATCH] some documentation changes --HG-- branch : trunk --- CHANGES | 2 +- MANIFEST.in | 3 ++- docs/src/designerdoc.txt | 28 ++++++++++++++++++++++++++-- docs/src/devrecipies.txt | 1 + docs/src/inheritance.txt | 8 +++++++- docs/src/installation.txt | 6 +++--- docs/src/loaders.txt | 1 + docs/src/objects.txt | 1 + docs/src/scopes.txt | 3 +++ jinja/loaders.py | 6 ++++-- setup.py | 32 ++++++++++++++++---------------- 11 files changed, 65 insertions(+), 26 deletions(-) diff --git a/CHANGES b/CHANGES index c791cd8..2a0a953 100644 --- a/CHANGES +++ b/CHANGES @@ -73,7 +73,7 @@ Version 1.2 "nonlocal" keyword. This means that you can now override variables defined in the outer scope from within a loop. -- ``foo + bar`` is now a simpler alternative to ``foo|string + bar|string`` +- ``foo ~ bar`` is now a simpler alternative to ``foo|string + bar|string`` - `PackageLoader` can now work without pkg_resources too diff --git a/MANIFEST.in b/MANIFEST.in index 60529d6..181a4aa 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,3 +1,4 @@ -include docs/build/*.html include Makefile CHANGES LICENSE AUTHORS TODO ez_setup.py +include docs/build/*.html +include docs/src/*.txt recursive-include tests * diff --git a/docs/src/designerdoc.txt b/docs/src/designerdoc.txt index c0ab8f6..1ca741d 100644 --- a/docs/src/designerdoc.txt +++ b/docs/src/designerdoc.txt @@ -67,6 +67,10 @@ this: If you have numerical indices you have to use the [] syntax: {{ users[0].username }} +*new in Jinja 1.2*: You can now use django like attributes for integer +indices. Thus ``{{ foo.0 }}`` is equivalent to ``{{ foo[0] }}``. + + Loops ===== @@ -235,6 +239,9 @@ can use expressions. In expressions you can use any of the following operators: ``//`` divide the left operand by the right one and return a truncated integer result: ``{{ 20 // 7 }}`` is ``2``. *added in Jinja 1.1* + ``~`` string concatenate a value with another one. ``{{ foo ~ bar }}`` + is equivalent to ``{{ foo|string + bar|string }}``. *added in + Jinja 1.1* ``*`` multiply the left operand with the right one. ``{{ 2 * 2 }}`` would return ``4``. ``**`` raise the left operand to the power of the right @@ -261,6 +268,18 @@ Note that there is no support for any bit operations or something similar. instead of ``not foo is bar`` and ``not foo in bar``. All other expressions require a prefix notation: ``not (foo and bar)``. + +With Jinja 1.2 onwards it's possible to replace basic if/else blocks with the +inline `if` / `else` expression. The following two examples evaluate to the +same: + +.. source:: jinja + + {{ "something" if expr else "otherthing" }} + + {% if expr %}something{% else %}otherthing{% endif %} + + Boolean Values ============== @@ -376,6 +395,7 @@ You can also specify more than one value: For information regarding the visibility of macros have a look at the `Scopes and Variable Behavior`_ section. + Extended Macro Call =================== @@ -465,6 +485,7 @@ templates. evaluated in an indepdendent environment by calling `rendertemplate`. See the documentation for this function in the `builtins`_ documentation. + Filtering Blocks ================ @@ -489,6 +510,7 @@ Of course you can chain filters too: returns ``"<b>some text</b>"``. + Defining Variables ================== @@ -504,12 +526,14 @@ This should ouput ``foobar``. For information regarding the visibility of variables have a look at the `Scopes and Variable Behavior`_ section. + Reserved Keywords ================= Jinja has some keywords you cannot use a variable names. This limitation -exists to make look coherent. Syntax highlighters won't mess things up and -you will don't have unexpected output. +exists to make templates look coherent. Syntax highlighters won't mess things +up and you won't have the situation that some names work depending on the +context. The following keywords exist and cannot be used as identifiers: diff --git a/docs/src/devrecipies.txt b/docs/src/devrecipies.txt index 2f97f7d..f0ec3c8 100644 --- a/docs/src/devrecipies.txt +++ b/docs/src/devrecipies.txt @@ -4,6 +4,7 @@ Recipies For Developers Here some recipies for application developers. + Automagic Template Variables ============================ diff --git a/docs/src/inheritance.txt b/docs/src/inheritance.txt index 2e3b7d7..0b7941a 100644 --- a/docs/src/inheritance.txt +++ b/docs/src/inheritance.txt @@ -69,7 +69,10 @@ A child template might look like this: The ``{% extends %}`` tag is the key here. It tells the template engine that this template "extends" another template. When the template system evaluates -this template, first it locates the parent. +this template, first it locates the parent. It must be always the first tag +in a template but whitespace or a comment is allowed before. This was not +enforced with Jinja 1.0 and 1.1, it does however raise a syntax error with +1.2 or later. The filename of the template depends on the template loader. For example the ``FileSystemLoader`` allows you to access other templates by giving the @@ -93,6 +96,7 @@ value from the parent template is used instead. two similarly-named ``{% block %}`` tags in a template, that template's parent wouldn't know which one of the blocks' content to use. + How Inheritance Works Internally ================================ @@ -138,6 +142,7 @@ an syntax error. Here some examples: However the condition is handled at runtime because it's in a valid block and defines a new block subtemplates can override. + Super Blocks ============ @@ -156,6 +161,7 @@ to get the data of the parent you can give it an offset: {{ super(2) }} return the data of the second parent block + Block Shortcuts =============== diff --git a/docs/src/installation.txt b/docs/src/installation.txt index b5b6394..5b48a07 100644 --- a/docs/src/installation.txt +++ b/docs/src/installation.txt @@ -36,8 +36,8 @@ Installing the development version If you want to play around with the code ---------------------------------------- -1. Install `Subversion`_ -2. ``svn co http://trac.pocoo.org/repos/jinja/trunk jinja`` +1. Install `mercurial`_ +2. ``svn co http://dev.pocoo.org/hg/jinja-main jinja`` 3. ``cd jinja`` 4. ``ln -s jinja /usr/lib/python2.X/site-packages`` @@ -70,4 +70,4 @@ number. .. _download page: http://jinja.pocoo.org/download.html .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools .. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall -.. _Subversion: http://subversion.tigris.org/ +.. _mercurial: http://www.selenic.com/mercurial/ diff --git a/docs/src/loaders.txt b/docs/src/loaders.txt index 0112ed3..f4480ac 100644 --- a/docs/src/loaders.txt +++ b/docs/src/loaders.txt @@ -149,6 +149,7 @@ This mixin requires the `python-memcached`_ library. .. _memcached: http://www.danga.com/memcached/ .. _python-memcached: http://www.tummy.com/Community/software/python-memcached/ + How Mixin Classes Work ====================== diff --git a/docs/src/objects.txt b/docs/src/objects.txt index 7b0641f..d1551ac 100644 --- a/docs/src/objects.txt +++ b/docs/src/objects.txt @@ -5,6 +5,7 @@ Global objects This section covers the behavior of global objects in the Jinja namespace and also the behavior of their attributes. + Functions ========= diff --git a/docs/src/scopes.txt b/docs/src/scopes.txt index 4938aca..baf8c69 100644 --- a/docs/src/scopes.txt +++ b/docs/src/scopes.txt @@ -5,6 +5,7 @@ Scopes and Variable Behavior This section of the documentation covers the Jinja behavior regarding variable visibility. + Scopes ====== @@ -30,6 +31,7 @@ Defined macros appear on the context as variables. Because of this, they are affected by the scoping too. A macro defined inside of a macro is just available in those two macros (the macro itself and the macro it's defined in). + Template Globals ================ @@ -106,6 +108,7 @@ You can of course also use the `|default` filter. it impossible to use conditional expressions for inclusion in non root templates. + Undefined Variables =================== diff --git a/jinja/loaders.py b/jinja/loaders.py index ecef455..24eaa47 100644 --- a/jinja/loaders.py +++ b/jinja/loaders.py @@ -266,13 +266,15 @@ class MemcachedLoaderMixin(object): """ Uses a memcached server to cache the templates. - Requires the memcache library from tummy__. + Requires the memcache library from `tummy`_ or the cmemcache library + from `Gijsbert de Haan`_. With Jinja 1.2 onwards you can also provide a `client` keyword argument that takes an already instanciated memcache client or memcache client like object. - __ http://www.tummy.com/Community/software/python-memcached/ + .. _tummy: http://www.tummy.com/Community/software/python-memcached/ + .. _Gisjsbert de Haan: http://gijsbert.org/cmemcache/ """ def __init__(self, use_memcache, memcache_time=60 * 60 * 24 * 7, diff --git a/setup.py b/setup.py index a07ef83..a7086c2 100644 --- a/setup.py +++ b/setup.py @@ -53,19 +53,19 @@ class optional_build_ext(build_ext): setup( - name = 'Jinja', - version = '1.2', - url = 'http://jinja.pocoo.org/', - license = 'BSD', - author = 'Armin Ronacher', - author_email = 'armin.ronacher@active-4.com', - description = 'A small but fast and easy to use stand-alone template ' - 'engine written in pure python.', + name='Jinja', + version='1.2', + url='http://jinja.pocoo.org/', + license='BSD', + author='Armin Ronacher', + author_email='armin.ronacher@active-4.com', + description='A small but fast and easy to use stand-alone template ' + 'engine written in pure python.', long_description = getdoc(jinja), # jinja is egg safe. But because we distribute the documentation # in form of html and txt files it's a better idea to extract the files - zip_safe = False, - classifiers = [ + zip_safe=False, + classifiers=[ 'Development Status :: 5 - Production/Stable', 'Environment :: Web Environment', 'Intended Audience :: Developers', @@ -76,9 +76,9 @@ setup( 'Topic :: Software Development :: Libraries :: Python Modules', 'Topic :: Text Processing :: Markup :: HTML' ], - keywords = ['python.templating.engines'], - packages = ['jinja', 'jinja.translators'], - data_files = [ + keywords=['python.templating.engines'], + packages=['jinja', 'jinja.translators'], + data_files=[ ('docs', list(list_files('docs/build'))), ('docs/txt', list(list_files('docs/src'))) ], @@ -86,8 +86,8 @@ setup( [python.templating.engines] jinja = jinja.plugin:BuffetPlugin ''', - extras_require = {'plugin': ['setuptools>=0.6a2']}, - features = { + extras_require={'plugin': ['setuptools>=0.6a2']}, + features={ 'speedups': Feature( 'optional C-speed enhancements', standard = True, @@ -103,5 +103,5 @@ setup( ] ) }, - cmdclass = {'build_ext': optional_build_ext} + cmdclass={'build_ext': optional_build_ext} ) -- 2.26.2