From: Armin Ronacher Date: Mon, 9 Jun 2008 16:27:19 +0000 (+0200) Subject: updated documentation X-Git-Tag: 2.0rc1~9 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3ef20437d9454fab3d13ac313875fef7d093e8fe;p=thirdparty%2Fjinja.git updated documentation --HG-- branch : trunk --- diff --git a/Makefile b/Makefile index 5728fdb0..6622bd10 100644 --- a/Makefile +++ b/Makefile @@ -14,8 +14,11 @@ test: test-coverage: @(cd tests; py.test -C $(TESTS)) -documentation: - @(cd docs; ./generate.py) +html-documentation: + @(cd docs; make html) + +pdf-documentation: + @(cd docs; make latex; cd _build/latex; make all-pdf) webpage: @(cd ../www; ./generate.py) diff --git a/docs/_static/darkmetal.png b/docs/_static/darkmetal.png new file mode 100644 index 00000000..4000a94b Binary files /dev/null and b/docs/_static/darkmetal.png differ diff --git a/docs/_static/jinja.js b/docs/_static/jinja.js new file mode 100644 index 00000000..1c042187 --- /dev/null +++ b/docs/_static/jinja.js @@ -0,0 +1,26 @@ +$(function() { + + var + toc = $('#toc').show(), + items = $('#toc > ul').hide(); + + $('#toc h3') + .click(function() { + if (items.is(':visible')) { + items.animate({ + height: 'hide', + opacity: 'hide' + }, 300, function() { + toc.removeClass('expandedtoc'); + }); + } + else { + items.animate({ + height: 'show', + opacity: 'show' + }, 400); + toc.addClass('expandedtoc'); + } + }); + +}); diff --git a/docs/_static/style.css b/docs/_static/style.css index c5894f6b..a52436d3 100644 --- a/docs/_static/style.css +++ b/docs/_static/style.css @@ -8,10 +8,11 @@ body { } div.footer { - border-top: 1px solid black; + border-top: 1px solid #111; padding: 8px; font-size: 11px; - text-align: right; + text-align: center; + letter-spacing: 0.5px; } div.footer a { @@ -19,17 +20,20 @@ div.footer a { } div.header { + margin: 0 -15px 0 -15px; background: url(headerbg.png) repeat-x; border-top: 6px solid #D20000; } div.relnav { - border-bottom: 1px solid #ACACAC; + border-bottom: 1px solid #111; background: url(navigation.png); + margin: 0 -15px 0 -15px; padding: 2px 20px 0 28px; line-height: 25px; color: #aaa; font-size: 12px; + text-align: center; } div.relnav a { @@ -45,8 +49,9 @@ div.relnav a:hover { #content { background-color: white; color: #111; - background: url(watermark.png) -110px 0; - padding: 0; + border-bottom: 1px solid black; + background: url(watermark.png) center 0; + padding: 0 15px 0 15px; margin: 0; } @@ -66,7 +71,7 @@ h1.heading:hover { } h1.heading a { - background: url(jinjabanner.png) no-repeat 20px 0; + background: url(jinjabanner.png) no-repeat center 0; display: block; width: 100%; height: 80px; @@ -89,12 +94,12 @@ h1.heading span { } #contentwrapper { - max-width: 700px; + max-width: 680px; padding: 0 18px 20px 18px; - margin: 0 0 0 10px; + margin: 0 auto 0 auto; border-right: 1px solid #eee; border-left: 1px solid #eee; - background: url(watermark_blur.png) -120px -114px; + background: url(watermark_blur.png) center -114px; } #contentwrapper h2, @@ -230,37 +235,9 @@ div.admonition-implementation { background: url(implementation.png) no-repeat 10px 40px; } -#toc { - margin: 20px 0 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: #B4B4B4!important; font-size: 0.8em; - margin-left: 8px; padding: 0 4px 0 4px; text-decoration: none!important; visibility: hidden; @@ -345,3 +322,64 @@ span.highlight { background-color: #eee; border: 1px solid #ccc; } + +#toc { + margin: 0 -17px 0 -17px; + display: none; +} + +#toc h3 { + float: right; + margin: 5px 5px 0 0; + padding: 0; + font-size: 12px; + color: #777; +} + +#toc h3:hover { + color: #333; + cursor: pointer; +} + +.expandedtoc { + background: #222 url(darkmetal.png); + border-bottom: 1px solid #111; + outline-bottom: 1px solid #000; + padding: 5px; +} + +.expandedtoc h3 { + color: #aaa; + margin: 0!important; +} + +.expandedtoc h3:hover { + color: white!important; +} + +#tod h3:hover { + color: white; +} + +#toc a { + color: #ddd; + text-decoration: none; +} + +#toc a:hover { + color: white; + text-decoration: underline; +} + +#toc ul { + margin: 5px 0 12px 17px; + padding: 0 7px 0 7px; +} + +#toc ul ul { + margin-bottom: 0; +} + +#toc ul li { + margin: 2px 0 0 0; +} diff --git a/docs/_static/watermark.png b/docs/_static/watermark.png index cc5eb33d..d791ea00 100644 Binary files a/docs/_static/watermark.png and b/docs/_static/watermark.png differ diff --git a/docs/_static/watermark_blur.png b/docs/_static/watermark_blur.png index 6f686832..06e799ec 100644 Binary files a/docs/_static/watermark_blur.png and b/docs/_static/watermark_blur.png differ diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html index c2add7d8..7d1a4d5a 100644 --- a/docs/_templates/layout.html +++ b/docs/_templates/layout.html @@ -16,6 +16,7 @@ + {%- endif %} {%- if use_opensearch and builder != 'htmlhelp' %} {{ next.title }} » {%- endif %} - {%- if display_toc %} -
-

Table Of Contents

- {{ toc }} -
- {%- endif %}
+ {%- if display_toc %} +
+

Table Of Contents

+ {{ toc }} +
+ {%- endif %} {% block body %}{% endblock %}
diff --git a/docs/faq.rst b/docs/faq.rst index 9f7112ef..2042fccf 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -128,13 +128,10 @@ instead that one can assign to a variable by using set:: I don't have the _speedups Module. Is Jinja slower now? -------------------------------------------------------- -To achieve a good performance with automatic escaping enabled the escaping -function is implemented also written in pure C and used if Jinja2 was -installed with the speedups module which automatically happens if a C -compiled is available on the system. It won't affect templates without -auto escaping much if that feature is not enabled. You may however -experience werid tracebacks if you are using a Python installation, for -more information see the next FAQ item. +To achieve a good performance with automatic escaping enabled, the escaping +function is also implemented in pure C and used if Jinja2 was installed with +the speedups module. This happens automatically if a C compiler is available +on the system during installation. My tracebacks look weird. What's happening? -------------------------------------------- @@ -145,3 +142,14 @@ Jinja2 is unable to provide correct debugging information and the traceback may be incomplete. There is currently no good workaround for Jython or the AppEngine as ctypes is unavailable there and it's not possible to use the speedups extension. + +Why is there no Python 2.3 support? +----------------------------------- + +Python 2.3 is missing a lot of features that are used heavily in Jinja2. This +decision was made as with the upcoming Python 2.6 and 3.0 versions it becomes +harder to maintain the code for older Python versions. If you really need +Python 2.3 support you either have to use `Jinja 1`_ or other templating +engines that still support 2.3. + +.. _Jinja 1: http://jinja.pocoo.org/1/ diff --git a/docs/jinjaext.py b/docs/jinjaext.py index 8a15d657..7dc9baf7 100644 --- a/docs/jinjaext.py +++ b/docs/jinjaext.py @@ -178,7 +178,6 @@ def jinja_nodes(dirname, arguments, options, content, lineno, doc.append('', '') doc.append('%s :Node type: :class:`%s`' % (p, node.__base__.__name__), '') - # XXX: sphinx bug? Expr gives a rst warning doc.append('', '') children = node.__subclasses__() children.sort(key=lambda x: x.__name__.lower()) @@ -188,8 +187,30 @@ def jinja_nodes(dirname, arguments, options, content, lineno, return parse_rst(state, content_offset, doc) +def inject_toc(app, doctree, docname): + titleiter = iter(doctree.traverse(nodes.title)) + try: + # skip first title, we are not interested in that one + titleiter.next() + title = titleiter.next() + # and check if there is at least another title + titleiter.next() + except StopIteration: + return + tocnode = nodes.section('') + tocnode['classes'].append('toc') + toctitle = nodes.section('') + toctitle['classes'].append('toctitle') + toctitle.append(nodes.title(text='Table Of Contents')) + tocnode.append(toctitle) + tocnode += doctree.document.settings.env.get_toc_for(docname)[0][1] + title.parent.insert(title.parent.children.index(title), tocnode) + + 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)) app.add_directive('jinjanodes', jinja_nodes, 0, (0, 0, 0)) + # uncomment for inline toc. links are broken unfortunately + ##app.connect('doctree-resolved', inject_toc) diff --git a/docs/templates.rst b/docs/templates.rst index 182ef946..11d9978f 100644 --- a/docs/templates.rst +++ b/docs/templates.rst @@ -218,6 +218,19 @@ precedes it. For better readability statements that start a block (such as # endfor +.. admonition:: Note + + Line statements can span multiple lines if there are open parentheses, + braces or brackets:: + + + + .. _template-inheritance: Template Inheritance diff --git a/jinja2/utils.py b/jinja2/utils.py index f4027046..b1c20b69 100644 --- a/jinja2/utils.py +++ b/jinja2/utils.py @@ -293,10 +293,12 @@ class Markup(unicode): """ __slots__ = () - def __new__(cls, base=u''): + def __new__(cls, base=u'', encoding=None, errors='strict'): if hasattr(base, '__html__'): base = base.__html__() - return unicode.__new__(cls, base) + if encoding is None: + return unicode.__new__(cls, base) + return unicode.__new__(cls, base, encoding, errors) def __html__(self): return self @@ -434,7 +436,7 @@ class _MarkupEscapeHelper(object): __getitem__ = lambda s, x: _MarkupEscapeHelper(s.obj[x]) __unicode__ = lambda s: unicode(escape(s.obj)) __str__ = lambda s: str(escape(s.obj)) - __repr__ = lambda s: str(repr(escape(s.obj))) + __repr__ = lambda s: str(escape(repr(s.obj))) __int__ = lambda s: int(s.obj) __float__ = lambda s: float(s.obj)