From: Armin Ronacher Date: Sun, 4 May 2008 17:56:34 +0000 (+0200) Subject: added style for html documentation X-Git-Tag: 2.0rc1~99 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=9d472dfefac5306f6901057f5ab174ee21563689;p=jinja2.git added style for html documentation --HG-- branch : trunk --- diff --git a/.hgignore b/.hgignore index 55d124f..0aa46ee 100644 --- a/.hgignore +++ b/.hgignore @@ -1,7 +1,7 @@ ^instance$ ^instance/ ^jinja2/.*\.so$ -^docs/_.* +^docs/_build ^(build|dist|Jinja2\.egg-info)/ \.py[co]$ \.DS_Store$ diff --git a/CHANGES b/CHANGES index 85ba238..0c8e30e 100644 --- a/CHANGES +++ b/CHANGES @@ -1,221 +1,8 @@ -Jinja Changelog +Jinja2 Changelog =============== -Version 1.3 +Version 2.0 ----------- -(codename to be selected, release around February 2007) +(codename to be selected, release around July 2008) -Version 1.2 ------------ -(codename to be hatsuyuki, released Nov 17th 2007) - -.. admonition:: Backwards Incompatible Changes - - - `call` is a keyword now - - the internal parser AST changed - - `extends` must be the first tag in a template - - the tuple literal yields tuples now, instead of lists. - -- environments now have a `translator_factory` parameter that allows - to change the translator without subclassing the environment. - -- fixed bug in buffet plugin regarding the package loader - -- once again improved debugger. - -- added `groupby` filter. - -- added `sameas` test function. - -- standalone parser. Jinja does not use the python parser any more and will - continue having the same semantics in any future python versions. This - was done in order to simplify updating Jinja to 2.6 and 3.0 and to support - non python syntax. - -- added support for ``expr1 if test else expr2`` (conditional expressions) - -- ``foo.0`` as alias for ``foo[0]`` is possible now. This is mainly for - django compatibility. - -- the filter operators has a much higher priority now which makes it - possible to do ``foo|filter + bar|filter``. - -- new AST. the return value of `Environment.parse` is now a Jinja AST and not - a Jinja-Python AST. This is also the only backwards incompatible change but - should not affect many users because this feature is more or less - undocumented and has few use cases. - -- tuple syntax returns tuples now and not lists any more. - -- the print directive and ``{{ variable }}`` syntax now accepts and implicit - tuple like the `for` and `cycle` tags. (``{{ 1, 2 }}`` is an implicit alias - for ``{{ (1, 2) }}` like ``{% for a, b in seq %}`` is for - ``{% for (a, b) in seq %}``. - -- tests called with *one* parameter don't need parentheses. This gives a more - natural syntax for the `sameas` test and some others: - ``{{ foo is sameas bar }}`` instead of ``{{ foo is sameas(bar) }}``. If you - however want to pass more than one argument you have to use parentheses - because ``{{ foo is sometest bar, baz }}`` is handled as - ``{{ (foo is sometest(bar), baz) }}``, so as tuple expression. - -- removed support for octal character definitions in strings such as - ``'\14'``, use ``'\x0c'`` now. - -- added regular expression literal. ``@/expr/flags`` equals - ``re.compile(r'(?flags)expr')``. This is useful for the `matching` test and - probably some others. - -- added set literal. We do not use python3's {1, 2} syntax because - this conflicts with the dict literal. To be compatible with the regex - literal we use ``@(1, 2)`` instead. - -- fixed bug in `get_attribute` that disallowed retreiving attributes of objects - without a `__class__` such as `_sre.SRE_Pattern`. - -- addded `django.contrib.jinja` which provides advanced support for django. - (thanks Bryan McLemore) - -- debugger is now able to rewrite the whole traceback, not only the first - frame. (requires the optional debugger c module which is compiled - automatically on installation if possible) - -- if the set that is postfixed with a bang (!) it acts like the python 3 - "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`` - -- `PackageLoader` can now work without pkg_resources too - -- added `getattribute` and `getitem` filter. - -- added support for the `pretty` library. - -- changed the way the `MemcachedLoaderMixin` creates the class so that it's - possible to hook your own client in. - - -Version 1.1 ------------ -(codename: sinka, released Jun 1, 2007) - -- blocks now support ``{{ super() }}`` to render the parent output. - -- debugging system improved, smaller filesize for the cached files. - Debugging works now well for any module using linecache. - -- ``{{ debug() }}`` can now be used to get a list of filters and - tags. - -- the template lexer keeps not track of brace, parenthesis and - bracket balance in order to not break variable tags apart if they - are configured to look like this: ``${expr}``. This also fixes - the problem with nested dicts in variable expressions. - -- it's now possible to configure the variable blocks to look the - same as the block delimiters. Thus you can set the syntax to something - like ``{ / }`` for both blocks and variables. - -- added whitespace management system for the template designer. - -- some small bugfixes. - -- improved security system regarding function calls and variable - assignment in for loops. - -- added `lipsum` function to generate random text. - -- strings without unicode characters are processed as binary strings now - to workaround problems with `datetime.strftime` which only accepts - binary strings. - -- it's now possible to use newlines in string literals - -- developer friendly traceback is now toggleable - -- the variable failure is now pluggable by replacing the undefined - singleton for an environment instance - -- fixed issue with old-style classes not implementing `__getitem__` - (thanks to Axel Böhm for discovering that bug) - -- added a bunch of new docstrings to the Jinja classes. Makes fun now to - use pydoc :-) - -- fixed severe memcaching bug. Formerly it wasn't possible to use memcaching - without enabling disk cache. - -- fixed a bug that allowed users to override the special names `_`, `true` etc. - -- added `batch` and `slice` filters for batching or slicing sequences - -- added `sum`, `abs`, `round` and `sort` filters. This fixes #238 - -- added `striptags` and `xmlattr` filters for easier SGML/XML processing - -- the trans tag does not need explicit naming for variables with the same - name any more. You can now use ``{% trans foo %}`` instead of the verbose - version ``{% trans foo=foo %}``. - -- reimplemented Buffet plugin so that it works at least for pylons - -- added `Environment.get_translations_for_string` - -- fixed a bug in the parser that didn't unescape keyword arguments. (thanks - to Alexey Melchakov for reporting) - -- You can now use the environment to just tokenize a template. This can - be useful for syntax highlighting or other purposes. - -- added optional C-implementation of the context baseclass. - -- you can now use optional parentheses around macro defintions. Thus it's - possible to write ``{% macro foo(a, b, c) %}`` instead of ``{% macro - foo a, b, c %}``. - -- additional macro arguments now end up in `varargs`. - -- implemented the `{% call %}` block. `call` and `endcall` can still be used - as identifiers until Jinja 1.3 - -- it's now possible to stream templates. - -- fixed a corner case when defining a block inside of a condition - -- the cached loader mixin is now able to cache multiple templates from - different loaders in the same cache folder. - -- Translatable strings returned by ``_()`` will leave their string formatting - signs untouched. Thanks to Stefan Ebner for reporting. - -- ``{% block name "data" %}`` is now an alias for - ``{% block name %}data{% endblock %}``. Note that the second argument can - be an expression. As soon as you specify an expression as second argument - the closing tag has to be omitted. - -- It's now possible to iterate over iterators additionally to sequences. - If the iterator is inifite it will crash however, so makes sure you don't - pass something like that to a template! - -- added `rendetemplate` to render included templates in an isolated - environment and get the outout back. - -- added `simplefilter` decorator. - -- improved ChoiceLoader error reporting (thanks to Bryan McLemore) - -- fixed extended slicing - -- reworked loader layer. All the cached loaders now have "private" non cached - baseclasses so that you can easily mix your own caching layers in. - -- added `MemcachedLoaderMixin` and `MemcachedFileSystemLoader` contributed - by Bryan McLemore. - - -Version 1.0 ------------ -(codename: siyutusan, released Mar 23, 2007) - -- Initial release +- initial release of Jinja2 diff --git a/docs/_static/headerbg.png b/docs/_static/headerbg.png new file mode 100644 index 0000000..035f9d4 Binary files /dev/null and b/docs/_static/headerbg.png differ diff --git a/docs/_static/jinjabanner.png b/docs/_static/jinjabanner.png new file mode 100644 index 0000000..c672118 Binary files /dev/null and b/docs/_static/jinjabanner.png differ diff --git a/docs/_static/style.css b/docs/_static/style.css new file mode 100644 index 0000000..7675bc2 --- /dev/null +++ b/docs/_static/style.css @@ -0,0 +1,256 @@ +body { + background-color: #333; + margin: 0; + padding: 0; + font-family: 'Georgia', serif; + font-size: 15px; + color: #eee; +} + +div.footer { + padding: 5px; + text-align: center; +} + +div.footer a { + color: #eee; +} + +div.header { + background: url(headerbg.png) repeat-x; + border-top: 6px solid #D20000; + border-bottom: 1px solid #ACACAC; + margin: -10px -10px 0 -10px; +} + +div.relnav { + border-top: 1px solid #F1F1F1; + border-bottom: 1px solid #ACACAC; + background-color: #ECECEC; + padding: 4px 20px 4px 28px; + margin: 0 -10px 10px -10px; + font-size: 13px; +} + +#content { + background-color: white; + color: #111; + background-image: url(watermark.png); + padding: 10px; + margin: 0; +} + +h1.heading { + margin: 0; + padding: 0; + height: 80px; + background-image: url(jinjabanner.png); + background-repeat: no-repeat; +} + +h1.heading a { + display: block; + width: 200px; + height: 80px; +} + +h1.heading span { + display: none; +} + +h2.subheading { + margin: -55px 0 35px 200px; + font-weight: normal; + font-size: 30px; + color: #444; +} + +h2.plain { + margin: 0; +} + +#jinjalogo { + background-image: url(jinjalogo.png); + background-repeat: no-repeat; + width: 400px; + height: 160px; +} + +#contentwrapper { + max-width: 700px; + padding: 0 0 20px 18px; +} + +#contentwrapper h3, +#contentwrapper h3 a { + color: #b41717; + font-size: 26px; + margin: 20px 0 0 -5px; +} + +#contentwrapper h4, +#contentwrapper h4 a { + color: #b41717; + font-size: 20px; + margin: 20px 0 0 0; +} + +table.docutils { + border-collapse: collapse; + border: 2px solid #aaa; + margin: 0.5em 1.5em 0.5em 1.5em; +} + +table.docutils td { + padding: 2px; + border: 1px solid #ddd; +} + +p, li, dd, dt, blockquote { + color: #333; +} + +p { + line-height: 150%; + margin-bottom: 0; + margin-top: 10px; + text-align: justify; +} + +hr { + border-top: 1px solid #ccc; + border-bottom: 0; + border-right: 0; + border-left: 0; + margin-bottom: 10px; + margin-top: 20px; +} + +dl { + margin-left: 10px; +} + +li, dt { + margin-top: 5px; +} + +dt { + font-weight: bold; +} + +th { + text-align: left; + padding: 3px; + background-color: #f2f2f2; +} + +a { + color: #b41717; +} + +a:hover { + color: #444; +} + +pre { + background-color: #f9f9f9; + border-top: 1px solid #ccc; + border-bottom: 1px solid #ccc; + padding: 5px; + font-size: 13px; + font-family: 'Bitstream Vera Sans Mono', 'Monaco', monospace; +} + +tt { + font-size: 13px; + font-family: 'Bitstream Vera Sans Mono', 'Monaco', monospace; + color: black; + padding: 1px 2px 1px 2px; + background-color: #f0f0f0; +} + +cite { + /* abusing , it's generated by ReST for `x` */ + font-size: 13px; + font-family: 'Bitstream Vera Sans Mono', 'Monaco', monospace; + font-weight: bold; + font-style: normal; +} + +div.admonition { + margin: 10px 0 10px 0; + padding: 10px; + border: 1px solid #ccc; + background-color: #f8f8f8; +} + +div.admonition p.admonition-title { + margin: -3px 0 5px 0; + font-weight: bold; + color: #b41717; + font-size: 16px; +} + +div.admonition p { + margin: 0 0 0 40px; +} + +#toc { + margin: 20px -10px 10px 15px; + padding: 10px; + width: 200px; + float: right; + background-color: #f8f8f8; + border: 1px solid #ccc; + border-right: none; +} + +#toc h3 { + font-size: 20px; + margin: 0 0 10px 0; + padding: 0; + color: #444; +} + +#toc ul { + margin: 0 0 0 30px; + padding: 0; +} + +#toc ul li { + padding: 0; + margin: 2px 0 2px 0; +} + +a.headerlink { + color: #A70000; + font-size: 0.8em; + margin-left: 8px; + padding: 0 4px 0 4px; + text-decoration: none!important; + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +a.headerlink:hover { + background-color: #A70000; + color: white!important; +} + +table.indextable { + width: 100%; +} + +table.indextable td { + vertical-align: top; + width: 50%; +} diff --git a/docs/_static/watermark.png b/docs/_static/watermark.png new file mode 100644 index 0000000..297d899 Binary files /dev/null and b/docs/_static/watermark.png differ diff --git a/docs/_templates/genindex.html b/docs/_templates/genindex.html new file mode 100644 index 0000000..2df98b6 --- /dev/null +++ b/docs/_templates/genindex.html @@ -0,0 +1,44 @@ +{% extends "layout.html" %} +{% title = 'Index' %} +{% block body %} + +

Index

+ + {% for key, dummy in genindexentries -%} + {{ key }} {% if not loop.last %}| {% endif %} + {%- endfor %} + +
+ + {% for key, entries in genindexentries %} +

{{ key }}

+
+
+{%- breakat = genindexcounts[loop.index0] // 2 %} +{%- numcols = 1 %} +{%- numitems = 0 %} +{% for entryname, (links, subitems) in entries %} +
{%- if links -%}{{ entryname|e }} + {%- for link in links[1:] %}, [Link]{% endfor -%} + {%- else -%} +{{ entryname|e }} + {%- endif -%}
+ {%- if subitems %} +
+ {%- for subentryname, subentrylinks in subitems %} +
{{ subentryname|e }} + {%- for link in subentrylinks[1:] %}, [Link]{% endfor -%} +
+ {%- endfor %} +
+ {%- endif -%} +{%- numitems = numitems + 1 + len(subitems) -%} +{%- if numcols < 2 and numitems > breakat -%} +{%- numcols = numcols+1 -%} +
+{%- endif -%} +{%- endfor %} +
+{% endfor %} + +{% endblock %} diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 0000000..83e48ae --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,72 @@ + + + + Jinja2 Documentation + + + + {%- if builder != 'htmlhelp' %} + + + + + {%- endif %} + {%- if use_opensearch and builder != 'htmlhelp' %} + + {%- endif %} + {%- if hasdoc('about') %} + + {%- endif %} + + + + {%- if hasdoc('copyright') %} + + {%- endif %} + + {%- if parents %} + + {%- endif %} + {%- if next %} + + {%- endif %} + {%- if prev %} + + {%- endif %} + + +
+
+

Jinja

+
+
+ {%- if prev %} + « {{ prev.title }} | + {%- endif %} + {{ title }} + {%- if next %} + | {{ next.title }} » + {%- endif %} +
+ {%- if display_toc %} +
+

Table Of Contents

+ {{ toc }} +
+ {%- endif %} +
+ {% block body %}{% endblock %} +
+
+
+ © Copyright 2008 by the Pocoo Team. +
+ + diff --git a/docs/_templates/opensearch.xml b/docs/_templates/opensearch.xml new file mode 100644 index 0000000..9f2fa42 --- /dev/null +++ b/docs/_templates/opensearch.xml @@ -0,0 +1,9 @@ + + + {{ project }} + Search {{ docstitle }} + utf-8 + + {{ docstitle }} + diff --git a/docs/_templates/page.html b/docs/_templates/page.html new file mode 100644 index 0000000..ee6cad3 --- /dev/null +++ b/docs/_templates/page.html @@ -0,0 +1,4 @@ +{% extends 'layout.html' %} +{% block body %} + {{ body }} +{% endblock %} diff --git a/docs/_templates/search.html b/docs/_templates/search.html new file mode 100644 index 0000000..82a78d0 --- /dev/null +++ b/docs/_templates/search.html @@ -0,0 +1,35 @@ +{% extends "layout.html" %} +{% title = 'Search' %} +{% block extrahead %} + +{% endblock %} +{% block body %} +

Search

+

+ From here you can search these documents. Enter your search + words into the box below and click "search". Note that the search + function will automatically search for all of the words. Pages + containing less words won't appear in the result list. +

+
+ + +
+ {% if search_performed %} +

Search Results

+ {% if not search_results %} +

Your search did not match any results.

+ {% endif %} + {% endif %} +
+ {% if search_results %} +
    + {% for href, caption, context in search_results %} +
  • {{ caption }} +
    {{ context|e }}
    +
    • + {% endfor %} +
+ {% endif %} +
+{% endblock %} diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 0000000..6e514be --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1,4 @@ +Changelog +========= + +.. jinjachangelog:: diff --git a/docs/conf.py b/docs/conf.py index 8a41874..91e1ca4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -76,7 +76,7 @@ pygments_style = 'jinjaext.JinjaStyle' # The style sheet to use for HTML and HTML Help pages. A file of that name # must exist either in Sphinx' static/ path, or in one of the custom paths # given in html_static_path. -html_style = 'default.css' +html_style = 'style.css' # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -95,15 +95,11 @@ html_last_updated_fmt = '%b %d, %Y' # typographically correct entities. #html_use_smartypants = True -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +# use jinja2 for templates +template_bridge = 'jinjaext.Jinja2Bridge' -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_use_modindex = True +# no modindex +html_use_modindex = False # If true, the reST sources are included in the HTML build as _sources/. #html_copy_source = True diff --git a/docs/index.rst b/docs/index.rst index d7b4d89..db5c1b5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,7 @@ -Welcome to Jinja2's documentation! -================================== +Jinja2 Documentation +==================== -Contents: +Welcome in the Jinja2 documentation. .. toctree:: :maxdepth: 2 @@ -9,3 +9,7 @@ Contents: intro api templates + + changelog + +* :ref:`genindex` diff --git a/docs/jinjaext.py b/docs/jinjaext.py index 57c7097..78aacf8 100644 --- a/docs/jinjaext.py +++ b/docs/jinjaext.py @@ -8,17 +8,20 @@ :copyright: Copyright 2008 by Armin Ronacher. :license: BSD. """ +import os import re import inspect +import jinja2 +from itertools import islice from types import BuiltinFunctionType from docutils import nodes from docutils.statemachine import ViewList from sphinx.ext.autodoc import prepare_docstring - - +from sphinx.application import TemplateBridge from pygments.style import Style from pygments.token import Keyword, Name, Comment, String, Error, \ Number, Operator, Generic +from jinja2 import Environment, FileSystemLoader class JinjaStyle(Style): @@ -60,6 +63,17 @@ class JinjaStyle(Style): Error: '#F00 bg:#FAA' } + +class Jinja2Bridge(TemplateBridge): + + def init(self, builder): + path = builder.config.templates_path + self.env = Environment(loader=FileSystemLoader(path)) + + def render(self, template, context): + return self.env.get_template(template).render(context) + + _sig_re = re.compile(r'^[a-zA-Z_][a-zA-Z0-9_]*(\(.*?\))') @@ -112,6 +126,28 @@ def dump_functions(mapping): return directive +def jinja_changelog(dirname, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + doc = ViewList() + changelog = file(os.path.join(os.path.dirname(jinja2.__file__), '..', + 'CHANGES')) + try: + for line in islice(changelog, 3, None): + doc.append(line.rstrip(), '') + finally: + changelog.close() + node = nodes.section() + # hack around title style bookkeeping + surrounding_title_styles = state.memo.title_styles + surrounding_section_level = state.memo.section_level + state.memo.title_styles = [] + state.memo.section_level = 0 + state.nested_parse(doc, content_offset, node, match_titles=1) + state.memo.title_styles = surrounding_title_styles + state.memo.section_level = surrounding_section_level + return node.children + + from jinja2.defaults import DEFAULT_FILTERS, DEFAULT_TESTS jinja_filters = dump_functions(DEFAULT_FILTERS) jinja_tests = dump_functions(DEFAULT_TESTS) @@ -120,3 +156,4 @@ jinja_tests = dump_functions(DEFAULT_TESTS) def setup(app): app.add_directive('jinjafilters', jinja_filters, 0, (0, 0, 0)) app.add_directive('jinjatests', jinja_tests, 0, (0, 0, 0)) + app.add_directive('jinjachangelog', jinja_changelog, 0, (0, 0, 0))