Permalink
Browse files

liberating jingo from zamboni

  • Loading branch information...
0 parents commit 5caec33a4d81ef8692bdcd53e818f4872be467c5 @jbalogh committed Feb 10, 2010
@@ -0,0 +1,2 @@
+docs/_build
+.py[co]
27 LICENSE
@@ -0,0 +1,27 @@
+Copyright (c) 2010, Jeff Balogh.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+ 1. Redistributions of source code must retain the above copyright notice,
+ this list of conditions and the following disclaimer.
+
+ 2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+
+ 3. Neither the name of jingo nor the names of its contributors may
+ be used to endorse or promote products derived from this software
+ without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,3 @@
+include LICENSE
+include README.rst
+prune examples
@@ -0,0 +1,10 @@
+
+=====
+Jingo
+=====
+
+``jingo`` is an adapter for using
+`Jinja2 <http://jinja.pocoo.org/2/documentation/>`_ templates within Django.
+
+
+See the full docs at http://jbalogh.me/projects/jingo.
@@ -0,0 +1,89 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = _build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ -rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/zamboni.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/zamboni.qhc"
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+ "run these through (pdf)latex."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
@@ -0,0 +1,30 @@
+import os
+import sys
+
+sys.path.append(os.path.abspath('..'))
+
+import jingo
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+extensions = ['sphinx.ext.autodoc']
+
+# General information about the project.
+project = u'Jingo'
+copyright = u'2010, The Zamboni Collective'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# version: The short X.Y version.
+# release: The full version, including alpha/beta/rc tags.
+version = release = jingo.__version__
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+exclude_trees = ['_build']
@@ -0,0 +1,100 @@
+.. _jingo:
+.. module:: jingo
+
+A page about Jingo.
+===================
+
+Jingo is an adapter for using
+`Jinja2 <http://jinja.pocoo.org/2/documentation/>`_ templates within Django.
+Why are we already replacing the templates? AMO's current PHP templates let you
+go hog-wild with logic in the templates, while Django is extremely restrictive.
+Jinja loosens those restrictions somewhat, providing a more powerful engine with
+the beauty of Django's templates. The tipping point for me was the verbosity of
+doing L10n in Django templates.
+
+
+Settings
+--------
+
+If you want to configure the Jinja environment, use ``JINJA_CONFIG`` in
+``settings.py``. It can be a dict or a function that returns a dict. ::
+
+ JINJA_CONFIG = {'autoescape': False}
+
+or ::
+
+ def JINJA_CONFIG():
+ return {'the_answer': 41 + 1}
+
+
+Rendering
+---------
+
+At this point, Jingo only provides two shortcuts for rendering templates.
+
+.. autofunction:: jingo.render
+
+ The basic usage is to pass an ``HttpRequest`` and a template name. All the
+ processors in ``settings.CONTEXT_PROCESSORS`` will be applied to the
+ context, just like when you use a ``RequestContext`` in Django. Any extra
+ keyword arguments are passed directly to ``http.HttpResponse``.
+
+.. autofunction:: jingo.views.direct_to_template
+
+
+Template Helpers
+----------------
+
+Instead of template tags, Jinja encourages you to add functions and filters to
+the templating environment. In ``jingo``, we call these helpers. When the
+Jinja environment is initialized, ``jingo`` will try to open a ``helpers.py``
+file from every app in ``INSTALLED_APPS``. Two decorators are provided to ease
+the environment extension:
+
+.. function:: jingo.register.filter
+
+ Adds the decorated function to Jinja's filter library.
+
+.. function:: jingo.register.function
+
+ Adds the decorated function to Jinja's global namespace.
+
+
+.. highlight:: jinja
+
+Default Helpers
+~~~~~~~~~~~~~~~
+
+Helpers are available in all templates automatically, without any extra
+loading.
+
+.. automodule:: jingo.helpers
+ :members:
+
+
+Template Environment
+--------------------
+
+A single Jinja ``Environment`` is created for use in all templates. This is
+available as ``jingo.env`` if you need to work with the ``Environment``.
+
+
+Localization
+------------
+
+Since we all love L10n, let's see what it looks like in Jinja templates::
+
+ <h2>{{ _('Reviews for {0}')|f(addon.name) }}</h2>
+
+The simple way is to use the familiar underscore and string within a ``{{ }}``
+moustache block. ``f`` is an interpolation filter documented below. Sphinx
+could create a link if I knew how to do that.
+
+The other method uses Jinja's ``trans`` tag::
+
+ {% trans user=review.user|user_link, date=review.created|datetime %}
+ by {{ user }} on {{ date }}
+ {% endtrans %}
+
+``trans`` is nice when you have a lot of text or want to inject some variables
+directly. Both methods are useful, pick the one that makes you happy.
No changes.
@@ -0,0 +1 @@
+JINJA_CONFIG = {}
@@ -0,0 +1,36 @@
+"""
+Creating standalone Django apps is a PITA because you're not in a project, so
+you don't have a settings.py file. I can never remember to define
+DJANGO_SETTINGS_MODULE, so I run these commands which get the right env
+automatically.
+"""
+import functools
+import os
+
+from fabric.api import local, cd, env
+from fabric.contrib.project import rsync_project
+
+NAME = os.path.basename(os.path.dirname(__file__))
+ROOT = os.path.abspath(os.path.dirname(__file__))
+
+os.environ['DJANGO_SETTINGS_MODULE'] = '%s-project.settings' % NAME
+os.environ['PYTHONPATH'] = os.pathsep.join([ROOT,
+ os.path.join(ROOT, 'examples')])
+
+env.hosts = ['jbalogh.me']
+
+local = functools.partial(local, capture=False)
+
+
+def doc(kind='html'):
+ with cd('docs'):
+ local('make clean %s' % kind)
+
+
+def test():
+ local('nosetests')
+
+
+def updoc():
+ doc('dirhtml')
+ rsync_project('p/%s' % NAME, 'docs/_build/dirhtml/', delete=True)
Oops, something went wrong.

0 comments on commit 5caec33

Please sign in to comment.