Hi, It's probably even a bit too early to switch the template engine, considering, that the first final e of jinja 2 was just a month ago, but jinja 1 will obviously become outdated sooner or later.
Therefore I put some effort in porting Sphinx templating to the new Jinja2
engine.
The attached patch provides a template bridge, sets this bridge as default,
updates the babel configuration and makes required changes to the
templates.
Note, that I'm not sure, whether the changes to the templates are backward
compatible with Jinja 1. Therefore jinja 1 templating might not work
anymore after application of this patch.
I tested it against the Sphinx documentation itself and my personal site.
Both build fine, but I can't guarantee, that there are not any visual
failures on the rendered sites, which have resulted from the changes to the
template syntax.
The attached patch definitely requires much more testing than I did, before
I'd recommend it for inclusion in Sphinx core.
Most likely Jinja 2 needs some time to grow mature, too, but early releases
give more time for testing.
--
Freedom is always the freedom of dissenters.
(Rosa Luxemburg)
Index: sphinx/templates/layout.html
===================================================================
--- sphinx/templates/layout.html (Revision 65858)
+++ sphinx/templates/layout.html (Arbeitskopie)
@@ -4,7 +4,7 @@
{%- endblock %}
{%- set reldelim1 = reldelim1 is not defined and ' »' or reldelim1 %}
{%- set reldelim2 = reldelim2 is not defined and ' |' or reldelim2 %}
-{%- macro relbar %}
+{%- macro relbar() %}
<div class="related">
<h3>{{ _('Navigation') }}</h3>
<ul>
@@ -24,7 +24,7 @@
</ul>
</div>
{%- endmacro %}
-{%- macro sidebar %}
+{%- macro sidebar() %}
{%- if builder != 'htmlhelp' %}
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
@@ -64,7 +64,7 @@
</ul>
{%- endif %}
{%- if customsidebar %}
- {{ rendertemplate(customsidebar) }}
+ {% include customsidebar %}
{%- endif %}
{%- block sidebarsearch %}
{%- if pagename != "search" %}
Index: sphinx/templates/modindex.html
===================================================================
--- sphinx/templates/modindex.html (Revision 65858)
+++ sphinx/templates/modindex.html (Arbeitskopie)
@@ -51,7 +51,7 @@
{% if fname %}<a href="{{ fname }}">{% endif -%}
<tt class="xref">{{ modname|e }}</tt>
{%- if fname %}</a>{% endif %}
- {%- if pform[0] %} <em>({{ pform|join(', ') }})</em>{% endif -%}
+ {%- if pform and pform[0] %} <em>({{ pform|join(', ') }})</em>{% endif -%}
</td><td>{% if dep %}<strong>{{ _('Deprecated')}}:</strong>{% endif %}
<em>{{ synops|e }}</em></td></tr>
{%- endif -%}
Index: sphinx/_jinja2.py
===================================================================
--- sphinx/_jinja2.py (Revision 0)
+++ sphinx/_jinja2.py (Revision 0)
@@ -0,0 +1,90 @@
+# -*- coding: utf-8 -*-
+
+"""
+ sphinx._jinja2
+ ==============
+
+ Glue code for jinja2.
+
+ :author: Sebastian Wiesner
+ :contact: [EMAIL PROTECTED]
+ :copyright: 2008 by Sebastian Wiesner
+ :license: MIT
+"""
+
+import codecs
+from os import path
+
+import jinja2
+
+from sphinx.util import mtimes_of_files
+from sphinx.application import TemplateBridge
+
+
+class SphinxLoader(jinja2.BaseLoader):
+ """
+ A jinja2 reimplementation of `sphinx._jinja.SphinxFileSystemLoader`.
+ """
+
+ def __init__(self, basepath, extpaths, encoding='utf-8'):
+ """
+ Creates a new loader for sphinx.
+
+ ``extpaths`` is a list of directories, which provide additional
+ templates to sphinx.
+
+ ``encoding`` is used to decode the templates into unicode strings.
+ Defaults to utf-8.
+
+ If ``basepath`` is set, this path is used to load sphinx core
+ templates. If False, these templates are loaded from the sphinx
+ package.
+ """
+ self.core_loader = jinja2.FileSystemLoader(basepath)
+ self.all_loaders = jinja2.ChoiceLoader(
+ [jinja2.FileSystemLoader(extpath) for extpath in extpaths] +
+ [self.core_loader])
+
+ def get_source(self, environment, template):
+ # exclamation mark forces loading from core
+ if template.startswith('!'):
+ return self.core_loader.get_source(environment, template[1:])
+ # check if the template is probably an absolute path
+ fs_path = template.replace('/', path.sep)
+ if path.isabs(fs_path):
+ if not path.exists(fs_path):
+ raise jinja2.TemplateNotFound(template)
+ f = codecs.open(fs_path, 'r', self.encoding)
+ try:
+ mtime = path.getmtime(path)
+ return (f.read(), fs_path,
+ lambda: mtime == path.getmtime(path))
+ finally:
+ f.close()
+ # finally try to load from custom templates
+ return self.all_loaders.get_source(environment, template)
+
+
+class BuiltinTemplates(TemplateBridge):
+ """
+ Interfaces the rendering environment of jinja2 for use in sphinx.
+ """
+
+ def init(self, builder):
+ base_templates_path = path.join(path.dirname(__file__), 'templates')
+ ext_templates_path = [path.join(builder.confdir, dir)
+ for dir in builder.config.templates_path]
+ self.templates_path = [base_templates_path] + ext_templates_path
+ loader = SphinxLoader(base_templates_path, ext_templates_path)
+ use_i18n = builder.translator is not None
+ extensions = use_i18n and ['jinja2.ext.i18n'] or []
+ self.environment = jinja2.Environment(loader=loader,
+ extensions=extensions)
+ if use_i18n:
+ self.environment.install_gettext_translations(builder.translator)
+
+ def render(self, template, context):
+ return self.environment.get_template(template).render(context)
+
+ def newest_template_mtime(self):
+ return max(mtimes_of_files(self.templates_path, '.html'))
Index: sphinx/builder.py
===================================================================
--- sphinx/builder.py (Revision 65858)
+++ sphinx/builder.py (Arbeitskopie)
@@ -89,7 +89,7 @@
self.templates = self.app.import_object(
self.config.template_bridge, 'template_bridge setting')()
else:
- from sphinx._jinja import BuiltinTemplates
+ from sphinx._jinja2 import BuiltinTemplates
self.templates = BuiltinTemplates()
self.templates.init(self)
Index: babel.cfg
===================================================================
--- babel.cfg (Revision 65858)
+++ babel.cfg (Arbeitskopie)
@@ -1,5 +1,3 @@
-[extractors]
-jinja = sphinx._jinja.babel_extract
[python: **.py]
-[jinja: **/templates/**.html]
-[jinja: **/templates/**.xml]
+[jinja2: **/templates/**.html]
+[jinja2: **/templates/**.xml]
signature.asc
Description: This is a digitally signed message part.
