diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/behind-the-scenes.txt | 2 | ||||
| -rw-r--r-- | docs/changelog.txt | 49 | ||||
| -rw-r--r-- | docs/conf.py | 5 | ||||
| -rw-r--r-- | docs/contributing.txt | 8 | ||||
| -rw-r--r-- | docs/jinja2.txt | 140 | ||||
| -rw-r--r-- | docs/quickstart.txt | 17 | ||||
| -rw-r--r-- | docs/settings.txt | 39 |
7 files changed, 228 insertions, 32 deletions
diff --git a/docs/behind-the-scenes.txt b/docs/behind-the-scenes.txt index c2f87d7..0cd2a3c 100644 --- a/docs/behind-the-scenes.txt +++ b/docs/behind-the-scenes.txt @@ -18,7 +18,7 @@ even know which files are concerned actually, since it doesn't look inside the nodelist of the template block enclosed by the ``compress`` template tag. The offline cache manifest is just a json file, stored on disk inside the directory that holds the compressed files. The format of the manifest is simply -a key <=> value dictionnary, with the hash of the nodelist being the key, +a key <=> value dictionary, with the hash of the nodelist being the key, and the HTML containing the element code for the combined file or piece of code being the value. Generating the offline manifest, using the ``compress`` management command, also generates the combined files referenced in the manifest. diff --git a/docs/changelog.txt b/docs/changelog.txt index 20c1373..3828197 100644 --- a/docs/changelog.txt +++ b/docs/changelog.txt @@ -1,14 +1,51 @@ Changelog ========= +v1.4 +---- + +- Added Python 3 compatibility. + +- Added compatibility with Django 1.6.x. + +- Fixed compatibility with html5lib 1.0. + +- Added offline compression for Jinja2 with Jingo and Coffin integration. + +- Improved support for template inheritance in offline compression. + +- Made offline compression avoid compressing the same block multiple times. + +- Added a ``testenv`` target in the Makefile to make it easier to set up the + test environment. + +- Allowed data-uri filter to handle external/protocol-relative references. + +- Made ``CssCompressor`` class easier to extend. + +- Added support for explictly stating the block being ended. + +- Added rcssmin and updated rjsmin. + +- Removed implicit requirement on BeautifulSoup. + +- Made GzipCompressorFileStorage set access and modified times to the same time + as the corresponding base file. + +- Defaulted to using django's simplejson, if present. + +- Fixed CompilerFilter to always output Unicode strings. + +- Fixed windows line endings in offline compression. + v1.3 (03/18/2013) ----------------- - *Backward incompatible changes* - - Dropped support for Python 2.5. Removed ``any`` and ``walk`` compatibility + - Dropped support for Python 2.5. Removed ``any`` and ``walk`` compatibility functions in ``compressor.utils``. - + - Removed compatibility with Django 1.2 for default values of some settings: - :attr:`~COMPRESS_ROOT` no longer uses ``MEDIA_ROOT`` if ``STATIC_ROOT`` is @@ -17,7 +54,7 @@ v1.3 (03/18/2013) - :attr:`~COMPRESS_URL` no longer uses ``MEDIA_URL`` if ``STATIC_URL`` is not defined. It expects ``STATIC_URL`` to be defined instead. - - :attr:`~COMPRESS_CACHE_BACKEND` no longer uses ``CACHE_BACKEND`` and simply + - :attr:`~COMPRESS_CACHE_BACKEND` no longer uses ``CACHE_BACKEND`` and simply defaults to ``default``. - Added precompiler class support. This enables you to write custom precompilers @@ -29,8 +66,8 @@ v1.3 (03/18/2013) - Removed a ``fsync()`` call in ``CompilerFilter`` to improve performance. We already called ``self.infile.flush()`` so that call was not necessary. -- Added an extension to provide django-sekizai support. - See :ref:`django-sekizai Support <django-sekizai_support>` for more +- Added an extension to provide django-sekizai support. + See :ref:`django-sekizai Support <django-sekizai_support>` for more information. - Fixed a ``DeprecationWarning`` regarding the use of ``django.utils.hashcompat`` @@ -44,7 +81,7 @@ v1.2 - Added contributing docs. Be sure to check them out and start contributing! -- Moved CI to Travis: http://travis-ci.org/jezdez/django_compressor +- Moved CI to Travis: http://travis-ci.org/django-compressor/django-compressor - Introduced a new ``compressed`` context dictionary that is passed to the templates that are responsible for rendering the compressed snippets. diff --git a/docs/conf.py b/docs/conf.py index a0b1ab7..34552c3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -42,7 +42,7 @@ master_doc = 'index' # General information about the project. project = u'Django Compressor' -copyright = u'2013, Django Compressor authors' +copyright = u'2014, Django Compressor authors' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -96,7 +96,8 @@ pygments_style = 'murphy' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +# html_theme = 'default' +RTD_NEW_THEME = True # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/contributing.txt b/docs/contributing.txt index ceff111..225a1ae 100644 --- a/docs/contributing.txt +++ b/docs/contributing.txt @@ -21,7 +21,7 @@ In a nutshell Here's what the contribution process looks like, in a bullet-points fashion, and only for the stuff we host on github: -#. Django Compressor is hosted on `github`_, at https://github.com/jezdez/django_compressor +#. Django Compressor is hosted on `github`_, at https://github.com/django-compressor/django-compressor #. The best method to contribute back is to create a github account, then fork the project. You can use this fork as if it was your own project, and should push your changes to it. @@ -116,9 +116,7 @@ requirements **in the virtualenv**:: $ virtualenv compressor_test $ source compressor_test/bin/activate - (compressor_test) $ pip install -e . - (compressor_test) $ pip install -r requirements/tests.txt - (compressor_test) $ pip install Django + (compressor_test) $ make testenv Then run ``make test`` to run the tests. Please note that this only tests django_compressor in the Python version you've created the virtualenv with @@ -160,7 +158,7 @@ double cookie points. Seriously. You rock. This very document is based on the contributing docs of the `django CMS`_ project. Many thanks for allowing us to steal it! -.. _Fork: http://github.com/jezdez/django_compressor +.. _Fork: http://github.com/django-compressor/django-compressor .. _Travis: http://travis-ci.org/ .. _`pull request announcment`: http://about.travis-ci.org/blog/announcing-pull-request-support/ .. _`Travis documentation`: http://about.travis-ci.org/docs/ diff --git a/docs/jinja2.txt b/docs/jinja2.txt index d23a65e..134b0b8 100644 --- a/docs/jinja2.txt +++ b/docs/jinja2.txt @@ -1,5 +1,5 @@ -Jinja2 Support -============== +Jinja2 In-Request Support +========================= Django Compressor comes with support for Jinja2_ via an extension. @@ -12,7 +12,7 @@ In order to use Django Compressor's Jinja2 extension we would need to pass import jinja2 from compressor.contrib.jinja2ext import CompressorExtension - env = jinja2.environment(extensions=[CompressorExtension]) + env = jinja2.Environment(extensions=[CompressorExtension]) From now on, you can use same code you'd normally use within Django templates:: @@ -37,5 +37,139 @@ module:: And that's it - our extension is loaded and ready to be used. + +Jinja2 Offline Compression Support +================================== +You'd need to configure ``COMPRESS_JINJA2_GET_ENVIRONMENT`` so that +Compressor can retrieve the Jinja2 environment for rendering. +This can be a lamda or function that returns a Jinja2 environment. + +Usage +----- +Run the following compress command along with an ``-engine`` parameter. The +parameter can be either jinja2 or django (default). For example, +"./manage.py compress -engine jinja2". + +Using both Django and Jinja2 templates +-------------------------------------- +There may be a chance that the Jinja2 parser is used to parse Django templates +if you have a mixture of Django and Jinja2 templates in the same location(s). +This should not be a problem since the Jinja2 parser will likely raise a +template syntax error, causing Compressor to skip the errorneous +template safely. (Vice versa for Django parser). + +A typical usage could be : + +- "./manage.py compress" for processing Django templates first, skipping + Jinja2 templates. +- "./manage.py compress -engine jinja2" for processing Jinja2 templates, + skipping Django templates. + +However, it is still recommended that you do not mix Django and Jinja2 +templates in the same project. + +Limitations +----------- +- Does not support ``{% import %}`` and similar blocks within + ``{% compress %}`` blocks. +- Does not support ``{{super()}}``. +- All other filters, globals and language constructs such as + ``{% if %}``, ``{% with %}`` and ``{% for %}`` are tested and + should run fine. + +Jinja2 templates location +------------------------- +IMPORTANT: For Compressor to discover the templates for offline compression, +there must be a template loader that implements the ``get_template_sources`` +method, and is in the ``TEMPLATE_LOADERS`` setting. + +If you're using Jinja2, you're likely to have a Jinja2 template loader in the +``TEMPLATE_LOADERS`` setting, otherwise Django won't know how to load Jinja2 +templates. You could use Jingo_ or your own custom loader. Coffin_ works +differently by providing a custom rendering method instead of a custom loader. + +Unfortunately, Jingo_ does not implement such a method in its loader; +Coffin_ does not seem to have a template loader in the first place. +Read on to understand how to make Compressor work nicely with Jingo_ +and Coffin_. + +By default, if you don't override the ``TEMPLATE_LOADERS`` setting, +it will include the app directories loader that searches for templates under +the ``templates`` directory in each app. If the app directories loader is in use +and your Jinja2 templates are in the ``<app>/templates`` directories, +Compressor will be able to find the Jinja2 templates. + +However, if you have Jinja2 templates in other location(s), you could include +the filesystem loader (``django.template.loaders.filesystem.Loader``) in the +``TEMPLATE_LOADERS`` setting and specify the custom location in the +``TEMPLATE_DIRS`` setting. + +For Jingo users +--------------- +You should configure ``TEMPLATE_LOADERS`` as such:: + + TEMPLATE_LOADERS = ( + 'jingo.Loader', + 'django.template.loaders.filesystem.Loader', + 'django.template.loaders.app_directories.Loader', + ) + + def COMPRESS_JINJA2_GET_ENVIRONMENT(): + # TODO: ensure the CompressorExtension is installed with Jingo via + # Jingo's JINJA_CONFIG setting. + # Additional globals, filters, tests, + # and extensions used within {%compress%} blocks must be configured + # with Jingo. + from jingo import env + + return env + +This will enable the Jingo_ loader to load Jinja2 templates and the other +loaders to report the templates location(s). + +For Coffin users +---------------- +You might want to configure ``TEMPLATE_LOADERS`` as such:: + + TEMPLATE_LOADERS = ( + 'django.template.loaders.filesystem.Loader', + 'django.template.loaders.app_directories.Loader', + ) + + def COMPRESS_JINJA2_GET_ENVIRONMENT(): + # TODO: ensure the CompressorExtension is installed with Coffin + # as described in the "In-Request Support" section above. + # Additional globals, filters, tests, + # and extensions used within {%compress%} blocks must be configured + # with Coffin. + from coffin.common import env + + return env + +Again, if you have the Jinja2 templates in the app template directories, you're +done here. Otherwise, specify the location in ``TEMPLATE_DIRS``. + +Using your custom loader +------------------------ +You should configure ``TEMPLATE_LOADERS`` as such:: + + TEMPLATE_LOADERS = ( + 'your_app.Loader', + ... other loaders (optional) ... + ) + +You could implement the `get_template_sources` method in your loader or make +use of the Django's builtin loaders to report the Jinja2 template location(s). + +Python 3 Support +---------------- +Jingo with Jinja2 are tested and work on Python 2.6, 2.7, and 3.3. +Coffin with Jinja2 are tested and work on Python 2.6 and 2.7 only. +Jinja2 alone (with custom loader) are tested and work on Python 2.6, 2.7 and +3.3 only. + + .. _Jinja2: http://jinja.pocoo.org/docs/ .. _Coffin: http://pypi.python.org/pypi/Coffin +.. _Jingo: https://jingo.readthedocs.org/en/latest/ + diff --git a/docs/quickstart.txt b/docs/quickstart.txt index d922c8b..4acfab2 100644 --- a/docs/quickstart.txt +++ b/docs/quickstart.txt @@ -32,6 +32,10 @@ Installation 'compressor.finders.CompressorFinder', ) +* Define :attr:`COMPRESS_ROOT <django.conf.settings.COMPRESS_ROOT>` in settings + if you don't have already ``STATIC_ROOT`` or if you want it in a different + folder. + .. _staticfiles: http://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/ .. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles @@ -55,17 +59,6 @@ dependencies. pip install django-appconf -- versiontools_ - - Used internally to handle versions better, this is - automatically installed when following the above - installation instructions. - - In case you're installing Django Compressor differently - (e.g. from the Git repo), make sure to install it, e.g.:: - - pip install versiontools - Optional ^^^^^^^^ @@ -104,4 +97,4 @@ Optional .. _html5lib: http://code.google.com/p/html5lib/ .. _`Slim It`: http://slimit.org/ .. _django-appconf: http://pypi.python.org/pypi/django-appconf/ -.. _versiontools: http://pypi.python.org/pypi/versiontools/
\ No newline at end of file +.. _versiontools: http://pypi.python.org/pypi/versiontools/ diff --git a/docs/settings.txt b/docs/settings.txt index c2d684c..0d3fd72 100644 --- a/docs/settings.txt +++ b/docs/settings.txt @@ -119,6 +119,18 @@ Backend settings The arguments passed to the compressor. + - ``compressor.filters.yuglify.YUglifyCSSFilter`` + + A filter that passes the CSS content to the `yUglify compressor`_. + + .. attribute:: COMPRESS_YUGLIFY_BINARY + + The yUglify compressor filesystem path. + + .. attribute:: COMPRESS_YUGLIFY_CSS_ARGUMENTS + + The arguments passed to the compressor. Defaults to --terminal. + - ``compressor.filters.cssmin.CSSMinFilter`` A filter that uses Zachary Voase's Python port of the YUI CSS compression @@ -184,6 +196,18 @@ Backend settings The arguments passed to the compressor. + - ``compressor.filters.yuglify.YUglifyJSFilter`` + + A filter that passes the JavaScript code to the `yUglify compressor`_. + + .. attribute:: COMPRESS_YUGLIFY_BINARY + + The yUglify compressor filesystem path. + + .. attribute:: COMPRESS_YUGLIFY_JS_ARGUMENTS + + The arguments passed to the compressor. + - ``compressor.filters.template.TemplateFilter`` A filter that renders the JavaScript code with Django templating system. @@ -195,6 +219,7 @@ Backend settings .. _rJSmin: http://opensource.perlig.de/rjsmin/ .. _`Google Closure compiler`: http://code.google.com/closure/compiler/ .. _`YUI compressor`: http://developer.yahoo.com/yui/compressor/ + .. _`yUglify compressor`: https://github.com/yui/yuglify .. _`Slim It`: http://slimit.org/ .. attribute:: COMPRESS_PRECOMPILERS @@ -206,7 +231,7 @@ Backend settings item: #. mimetype - The mimetype of the file or inline code should that should be compiled. + The mimetype of the file or inline code that should be compiled. #. command_or_filter The command to call on each of the files. Modern Python string @@ -334,7 +359,7 @@ Caching settings .. attribute:: COMPRESS_CACHE_BACKEND - :Default: ``"default"`` or ``CACHE_BACKEND`` + :Default: ``CACHES["default"]`` or ``CACHE_BACKEND`` The backend to use for caching, in case you want to use a different cache backend for Django Compressor. @@ -367,7 +392,7 @@ Caching settings :Default: ``10`` The amount of time (in seconds) to cache the modification timestamp of a - file. Disabled by default. Should be smaller than + file. Should be smaller than :attr:`~django.conf.settings.COMPRESS_REBUILD_TIMEOUT` and :attr:`~django.conf.settings.COMPRESS_MINT_DELAY`. @@ -393,6 +418,14 @@ Caching settings and the ``django.core.context_processors.request`` context processor. .. _RequestContext: http://docs.djangoproject.com/en/dev/ref/templates/api/#django.template.RequestContext + +.. attribute:: COMPRESS_CACHE_KEY_FUNCTION + + :Default: ``'compressor.cache.simple_cachekey'`` + + The function to use when generating the cache key. The function must take + one argument which is the partial key based on the source's hex digest. + It must return the full key as a string. Offline settings ---------------- |