openstack/deb-python-django-compressor
Code Issues Proposed changes

Cleaned up the settings documentation and the docs frontpage.

Browse Source
This commit is contained in:
Jannis Leidel
2011-12-15 00:07:16 +01:00
parent 898199f05a
commit 78df87d733
6 changed files with 338 additions and 336 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/changelog.txt
View File

@@ -79,8 +79,8 @@ v1.1
manifest.json file). manifest.json file).
You can now easily run the :ref:`compress <pre-compression>` management You can now easily run the :ref:`compress <pre-compression>` management
command locally and transfer the :ref:`COMPRESS_ROOT <compress_root>` dir command locally and transfer the :attr:`~django.conf.settings.COMPRESS_ROOT`
to your server. dir to your server.
- Updated installation instructions to properly mention all dependencies, - Updated installation instructions to properly mention all dependencies,
even those internally used. even those internally used.
@@ -257,7 +257,7 @@ Major improvements and a lot of bugfixes, some of which are:
- New precompilation support, which allows compilation of files and - New precompilation support, which allows compilation of files and
hunks with easily configurable compilers before calling the actual hunks with easily configurable compilers before calling the actual
output filters. See the output filters. See the
:ref:`COMPRESS_PRECOMPILERS <compress_precompilers>` for more details. :attr:`~django.conf.settings.COMPRESS_PRECOMPILERS` for more details.
- New staticfiles support. With the introduction of the staticfiles app - New staticfiles support. With the introduction of the staticfiles app
to Django 1.3, compressor officially supports finding the files to to Django 1.3, compressor officially supports finding the files to
@@ -272,7 +272,7 @@ Major improvements and a lot of bugfixes, some of which are:
- Various perfomance improvements by better caching and mtime cheking. - Various perfomance improvements by better caching and mtime cheking.
- Deprecated ``COMPRESS_LESSC_BINARY`` setting because it's now - Deprecated ``COMPRESS_LESSC_BINARY`` setting because it's now
superseded by the :ref:`COMPRESS_PRECOMPILERS <compress_precompilers>` superseded by the :attr:`~django.conf.settings.COMPRESS_PRECOMPILERS`
setting. Just make sure to use the correct mimetype when linking to less setting. Just make sure to use the correct mimetype when linking to less
files or adding inline code and add the following to your settings:: files or adding inline code and add the following to your settings::

2
docs/index.txt
View File

@@ -33,7 +33,7 @@ Contents
======== ========
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 2
installation installation
usage usage

95
docs/installation.txt
View File

@@ -1,5 +1,8 @@
Quickstart
==========
Installation Installation
============ ------------
* Install Django Compressor with your favorite Python package manager:: * Install Django Compressor with your favorite Python package manager::
@@ -18,14 +21,16 @@ Installation
* In case you use Django 1.3's staticfiles_ contrib app (or its standalone * In case you use Django 1.3's staticfiles_ contrib app (or its standalone
counterpart django-staticfiles_) you have to add Django Compressor's file counterpart django-staticfiles_) you have to add Django Compressor's file
finder to the ``STATICFILES_FINDERS`` setting, for example with finder to the ``STATICFILES_FINDERS`` setting, for example with
``django.contrib.staticfiles``:: ``django.contrib.staticfiles``:
STATICFILES_FINDERS = ( .. code-block:: python
'django.contrib.staticfiles.finders.FileSystemFinder',
'django.contrib.staticfiles.finders.AppDirectoriesFinder', STATICFILES_FINDERS = (
# other finders.. 'django.contrib.staticfiles.finders.FileSystemFinder',
'compressor.finders.CompressorFinder', 'django.contrib.staticfiles.finders.AppDirectoriesFinder',
) # other finders..
'compressor.finders.CompressorFinder',
)
.. _staticfiles: http://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/ .. _staticfiles: http://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/
.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles .. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles
@@ -35,59 +40,63 @@ Installation
Dependencies Dependencies
------------ ------------
django-appconf_ (required) Required
^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^
Used internally to handle Django's settings, this is In case you're installing Django Compressor differently
automatically installed when following the above (e.g. from the Git repo), make sure to install the following
installation instructions. In case you're installing dependencies.
Django Compressor differently, make sure to install
it, e.g.::
pip install django-appconf - django-appconf_
versiontools_ (required) Used internally to handle Django's settings, this is
^^^^^^^^^^^^^^^^^^^^^^^^ automatically installed when following the above
installation instructions.
Used internally to handle versions better, this is pip install django-appconf
automatically installed when following the above
installation instructions. In case you're installing
Django Compressor differently, make sure to install
it, e.g.::
pip install versiontools - versiontools_
BeautifulSoup_ (optional) Used internally to handle versions better, this is
^^^^^^^^^^^^^^^^^^^^^^^^^ automatically installed when following the above
installation instructions.
for the :ref:`parser <compress_parser>` In case you're installing Django Compressor differently
``compressor.parser.BeautifulSoupParser`` and (e.g. from the Git repo), make sure to install it, e.g.::
``compressor.parser.LxmlParser``::
pip install BeautifulSoup<=4.0 pip install versiontools
lxml_ (optional) Optional
^^^^^^^^^^^^^^^^ ^^^^^^^^
for the :ref:`parser <compress_parser>` ``compressor.parser.LxmlParser``, - BeautifulSoup_
also requires libxml2_::
STATIC_DEPS=true pip install lxml For the :attr:`parser <django.conf.settings.COMPRESS_PARSER>`
``compressor.parser.BeautifulSoupParser`` and
``compressor.parser.LxmlParser``::
html5lib_ (optional) pip install BeautifulSoup<=4.0
^^^^^^^^^^^^^^^^^^^^
for the :ref:`parser <compress_parser>` ``compressor.parser.Html5LibParser``:: - lxml_
pip install html5lib For the :attr:`parser <django.conf.settings.COMPRESS_PARSER>`
``compressor.parser.LxmlParser``, also requires libxml2_::
`Slim It`_ (optional) STATIC_DEPS=true pip install lxml
^^^^^^^^^^^^^^^^^^^^^
for the :ref:`Slim It filter <slimit_filter>` ``compressor.filters.jsmin.SlimItFilter``:: - html5lib_
pip install slimit For the :attr:`parser <django.conf.settings.COMPRESS_PARSER>`
``compressor.parser.Html5LibParser``::
pip install html5lib
- `Slim It`_
For the :ref:`Slim It filter <slimit_filter>`
``compressor.filters.jsmin.SlimItFilter``::
pip install slimit
.. _BeautifulSoup: http://www.crummy.com/software/BeautifulSoup/ .. _BeautifulSoup: http://www.crummy.com/software/BeautifulSoup/
.. _lxml: http://codespeak.net/lxml/ .. _lxml: http://codespeak.net/lxml/

18
docs/remote-storages.txt
View File

@@ -9,9 +9,12 @@ processes files, it requires the files to be processed (in the
``{% compress %}`` block) to be available in a local file system cache. ``{% compress %}`` block) to be available in a local file system cache.
Django Compressor provides hooks to automatically have compressed files Django Compressor provides hooks to automatically have compressed files
pushed to a remote storage backend. Simply pushed to a remote storage backend. Simply set the storage backend
:ref:`set the storage backend <compress_storage>` that saves the result to a that saves the result to a remote service (see
remote service. :attr:`~django.conf.settings.COMPRESS_STORAGE`).
django-storages
^^^^^^^^^^^^^^^
So assuming your CDN is `Amazon S3`_, you can use the boto_ storage backend So assuming your CDN is `Amazon S3`_, you can use the boto_ storage backend
from the 3rd party app `django-storages`_. Some required settings are:: from the 3rd party app `django-storages`_. Some required settings are::
@@ -43,7 +46,7 @@ provides a management command to collect static files from various
locations which uses a storage backend, this is where both apps can be locations which uses a storage backend, this is where both apps can be
integrated. integrated.
#. Make sure the :ref:`COMPRESS_ROOT <compress_root>` and STATIC_ROOT_ #. Make sure the :attr:`~django.conf.settings.COMPRESS_ROOT` and STATIC_ROOT_
settings are equal since both apps need to look at the same directories settings are equal since both apps need to look at the same directories
when to do their job. when to do their job.
@@ -68,13 +71,14 @@ integrated.
self.local_storage._save(name, content) self.local_storage._save(name, content)
return name return name
#. Set your :ref:`COMPRESS_STORAGE <compress_storage>` and STATICFILES_STORAGE_ #. Set your :attr:`~django.conf.settings.COMPRESS_STORAGE` and STATICFILES_STORAGE_
settings to the dotted path of your custom cached storage backend, e.g. settings to the dotted path of your custom cached storage backend, e.g.
``'mysite.storage.CachedS3BotoStorage'``. ``'mysite.storage.CachedS3BotoStorage'``.
#. To have Django correctly render the URLs to your static files, set the #. To have Django correctly render the URLs to your static files, set the
STATIC_URL_ setting to the same value as :ref:`COMPRESS_URL <compress_url>` STATIC_URL_ setting to the same value as
(e.g. ``"http://compressor-test.s3.amazon.com/"``). :attr:`~django.conf.settings.COMPRESS_URL` (e.g.
``"http://compressor-test.s3.amazon.com/"``).
.. _CDN: http://en.wikipedia.org/wiki/Content_delivery_network .. _CDN: http://en.wikipedia.org/wiki/Content_delivery_network
.. _Amazon S3: https://s3.amazonaws.com/ .. _Amazon S3: https://s3.amazonaws.com/

524
docs/settings.txt
View File

@@ -1,424 +1,410 @@
.. _settings: .. _settings:
Settings Settings
-------- ========
.. currentmodule:: django.conf.settings
Django Compressor has a number of settings that control its behavior. Django Compressor has a number of settings that control its behavior.
They've been given sensible defaults. They've been given sensible defaults.
.. _compress_enabled: Base settings
-------------
COMPRESS_ENABLED .. attribute:: COMPRESS_ENABLED
^^^^^^^^^^^^^^^^
:Default: the opposite of ``DEBUG`` :default: the opposite of ``DEBUG``
Boolean that decides if compression will happen. To test compression Boolean that decides if compression will happen. To test compression
when ``DEBUG`` is ``True`` COMPRESS_ENABLED_ must also be set to ``True``. when ``DEBUG`` is ``True`` ``COMPRESS_ENABLED`` must also be set to
``True``.
When COMPRESS_ENABLED_ is ``False`` the input will be rendered without any When ``COMPRESS_ENABLED`` is ``False`` the input will be rendered without
compression except for code with a mimetype matching one listed in the any compression except for code with a mimetype matching one listed in the
COMPRESS_PRECOMPILERS_ setting. These matching files are still passed to the :attr:`~django.conf.settings.COMPRESS_PRECOMPILERS` setting. These
precompiler before rendering. matching files are still passed to the precompiler before rendering.
An example for some javascript and coffeescript. An example for some javascript and coffeescript.
.. code-block:: django .. code-block:: django
{% load compress %} {% load compress %}
{% compress js %} {% compress js %}
<script type="text/javascript" src="/static/js/site-base.js" /> <script type="text/javascript" src="/static/js/site-base.js" />
<script type="text/coffeescript" charset="utf-8" src="/static/js/awesome.coffee" /> <script type="text/coffeescript" charset="utf-8" src="/static/js/awesome.coffee" />
{% endcompress %} {% endcompress %}
With COMPRESS_ENABLED_ set to ``False`` this would give you something like With ``COMPRESS_ENABLED`` set to ``False`` this would give you something
this:: like this::
<script type="text/javascript" src="/static/js/site-base.js"></script> <script type="text/javascript" src="/static/js/site-base.js"></script>
<script type="text/javascript" src="/static/CACHE/js/8dd1a2872443.js" charset="utf-8"></script> <script type="text/javascript" src="/static/CACHE/js/8dd1a2872443.js" charset="utf-8"></script>
.. attribute:: COMPRESS_URL
:Default: ``STATIC_URL`` (``MEDIA_URL`` for older Django versions)
.. _compress_url: Controls the URL that linked files will be read from and compressed files
will be written to.
COMPRESS_URL .. note::
^^^^^^^^^^^^
:Default: ``STATIC_URL`` (``MEDIA_URL`` for older Django versions) This setting defaults to ``MEDIA_URL`` in case ``STATIC_URL``
is not given or empty, e.g. on older Django versions (< 1.3).
Controls the URL that linked files will be read from and compressed files .. attribute:: COMPRESS_ROOT
will be written to.
.. note:: :Default: ``STATIC_ROOT`` (``MEDIA_ROOT`` for older Django versions)
This setting defaults to ``MEDIA_URL`` in case ``STATIC_URL`` Controls the absolute file path that linked static will be read from and
is not given or empty, e.g. on older Django versions (<1.3). compressed static will be written to when using the default
:attr:`~django.conf.settings.COMPRESS_STORAGE`
``compressor.storage.CompressorFileStorage``.
.. _compress_root: .. note::
COMPRESS_ROOT This setting defaults to ``MEDIA_ROOT`` in case ``STATIC_ROOT``
^^^^^^^^^^^^^ is not given, e.g. on older Django versions (< 1.3).
:Default: ``STATIC_ROOT`` (``MEDIA_ROOT`` for older Django versions) .. attribute:: COMPRESS_OUTPUT_DIR
Controls the absolute file path that linked static will be read from and :Default: ``'CACHE'``
compressed static will be written to when using the default COMPRESS_STORAGE_
``compressor.storage.CompressorFileStorage``.
.. note:: Controls the directory inside :attr:`~django.conf.settings.COMPRESS_ROOT`
that compressed files will be written to.
This setting defaults to ``MEDIA_ROOT`` in case ``STATIC_ROOT`` Backend settings
is not given, e.g. on older Django versions (<1.3). ----------------
COMPRESS_OUTPUT_DIR .. attribute:: COMPRESS_CSS_FILTERS
^^^^^^^^^^^^^^^^^^^
:Default: ``'CACHE'`` :default: ``['compressor.filters.css_default.CssAbsoluteFilter']``
Controls the directory inside COMPRESS_ROOT_ that compressed files will A list of filters that will be applied to CSS.
be written to.
.. _compress_css_filters: Possible options are (including their settings):
COMPRESS_CSS_FILTERS - ``compressor.filters.css_default.CssAbsoluteFilter``
^^^^^^^^^^^^^^^^^^^^
:Default: ``['compressor.filters.css_default.CssAbsoluteFilter']`` A filter that normalizes the URLs used in ``url()`` CSS statements.
A list of filters that will be applied to CSS. .. attribute:: COMPRESS_CSS_HASHING_METHOD
Possible options are: The method to use when calculating the hash to append to
processed URLs. Either ``'mtime'`` (default) or ``'content'``.
Use the latter in case you're using multiple server to serve your
static files.
``compressor.filters.css_default.CssAbsoluteFilter`` - ``compressor.filters.csstidy.CSSTidyFilter``
""""""""""""""""""""""""""""""""""""""""""""""""""""
A filter that normalizes the URLs used in ``url()`` CSS statements. A filter that passes the CSS content to the CSSTidy_ tool.
- ``COMPRESS_CSS_HASHING_METHOD`` -- The method to use when calculating .. attribute:: COMPRESS_CSSTIDY_BINARY
the hash to append to processed URLs. Either ``'mtime'`` (default) or
``'content'``. Use the latter in case you're using multiple server to
serve your static files.
``compressor.filters.csstidy.CSSTidyFilter`` The CSSTidy binary filesystem path.
""""""""""""""""""""""""""""""""""""""""""""
A filter that passes the CSS content to the CSSTidy_ tool. .. attribute:: COMPRESS_CSSTIDY_ARGUMENTS
- ``COMPRESS_CSSTIDY_BINARY`` -- The CSSTidy binary filesystem path. The arguments passed to CSSTidy.
- ``COMPRESS_CSSTIDY_ARGUMENTS`` -- The arguments passed to CSSTidy. - ``compressor.filters.datauri.DataUriFilter``
``compressor.filters.datauri.DataUriFilter`` A filter for embedding media as `data: URIs`_ in the CSS.
""""""""""""""""""""""""""""""""""""""""""""
A filter for embedding media as `data: URIs`_ in the CSS. .. attribute:: COMPRESS_DATA_URI_MAX_SIZE
- ``COMPRESS_DATA_URI_MAX_SIZE`` -- Only files that are smaller than Only files that are smaller than this in bytes value will be embedded.
this value will be embedded. In bytes.
``compressor.filters.yui.YUICSSFilter`` - ``compressor.filters.yui.YUICSSFilter``
"""""""""""""""""""""""""""""""""""""""
A filter that passes the CSS content to the `YUI compressor`_. A filter that passes the CSS content to the `YUI compressor`_.
- ``COMPRESS_YUI_BINARY`` -- The YUI compressor filesystem path. Make sure .. attribute:: COMPRESS_YUI_BINARY
to also prepend this setting with ``java -jar`` if you use that kind of
distribution.
- ``COMPRESS_YUI_CSS_ARGUMENTS``-- The arguments passed to the compressor. The YUI compressor filesystem path. Make sure to also prepend this
setting with ``java -jar`` if you use that kind of distribution.
``compressor.filters.cssmin.CSSMinFilter`` .. attribute:: COMPRESS_YUI_CSS_ARGUMENTS
""""""""""""""""""""""""""""""""""""""""""
A filter that uses Zachary Voase's Python port of the YUI CSS compression The arguments passed to the compressor.
algorithm cssmin_.
.. _CSSTidy: http://csstidy.sourceforge.net/ - ``compressor.filters.cssmin.CSSMinFilter``
.. _`data: URIs`: http://en.wikipedia.org/wiki/Data_URI_scheme
.. _cssmin: http://pypi.python.org/pypi/cssmin/ A filter that uses Zachary Voase's Python port of the YUI CSS compression
algorithm cssmin_.
.. _CSSTidy: http://csstidy.sourceforge.net/
.. _`data: URIs`: http://en.wikipedia.org/wiki/Data_URI_scheme
.. _cssmin: http://pypi.python.org/pypi/cssmin/
.. _compress_js_filters: .. _compress_js_filters:
COMPRESS_JS_FILTERS .. attribute:: COMPRESS_JS_FILTERS
^^^^^^^^^^^^^^^^^^^
:Default: ``['compressor.filters.jsmin.JSMinFilter']`` :Default: ``['compressor.filters.jsmin.JSMinFilter']``
A list of filters that will be applied to javascript. Possible options are: A list of filters that will be applied to javascript.
``compressor.filters.jsmin.JSMinFilter`` Possible options are:
"""""""""""""""""""""""""""""""""""""""""
A filter that uses the jsmin implementation rJSmin_ to compress JavaScript code. - ``compressor.filters.jsmin.JSMinFilter``
.. _slimit_filter: A filter that uses the jsmin implementation rJSmin_ to compress
JavaScript code.
``compressor.filters.jsmin.SlimItFilter`` .. _slimit_filter:
"""""""""""""""""""""""""""""""""""""""""
A filter that uses the jsmin implementation `Slim It`_ to compress JavaScript code. - ``compressor.filters.jsmin.SlimItFilter``
``compressor.filters.closure.ClosureCompilerFilter`` A filter that uses the jsmin implementation `Slim It`_ to compress
"""""""""""""""""""""""""""""""""""""""""""""""""""" JavaScript code.
A filter that uses `Google Closure compiler`_. - ``compressor.filters.closure.ClosureCompilerFilter``
- ``COMPRESS_CLOSURE_COMPILER_BINARY`` -- The Closure compiler filesystem A filter that uses `Google Closure compiler`_.
path. Make sure to also prepend this setting with ``java -jar`` if you
use that kind of distribution. .. attribute:: COMPRESS_CLOSURE_COMPILER_BINARY
- ``COMPRESS_CLOSURE_COMPILER_ARGUMENTS`` -- The arguments passed to the compiler. The Closure compiler filesystem path. Make sure to also prepend
this setting with ``java -jar`` if you use that kind of distribution.
``compressor.filters.yui.YUIJSFilter`` .. attribute:: COMPRESS_CLOSURE_COMPILER_ARGUMENTS
""""""""""""""""""""""""""""""""""""""
A filter that passes the JavaScript code to the `YUI compressor`_. The arguments passed to the compiler.
- ``COMPRESS_YUI_BINARY`` -- The YUI compressor filesystem path. - ``compressor.filters.yui.YUIJSFilter``
- ``COMPRESS_YUI_JS_ARGUMENTS`` -- The arguments passed to the compressor. A filter that passes the JavaScript code to the `YUI compressor`_.
.. _rJSmin: http://opensource.perlig.de/rjsmin/ .. attribute:: COMPRESS_YUI_BINARY
.. _`Google Closure compiler`: http://code.google.com/closure/compiler/
.. _`YUI compressor`: http://developer.yahoo.com/yui/compressor/
.. _`Slim It`: http://slimit.org/
.. _compress_precompilers: The YUI compressor filesystem path.
COMPRESS_PRECOMPILERS .. attribute:: COMPRESS_YUI_JS_ARGUMENTS
^^^^^^^^^^^^^^^^^^^^^
:Default: ``()`` The arguments passed to the compressor.
An iterable of two-tuples whose first item is the mimetype of the files or .. _rJSmin: http://opensource.perlig.de/rjsmin/
hunks you want to compile with the command specified as the second item: .. _`Google Closure compiler`: http://code.google.com/closure/compiler/
.. _`YUI compressor`: http://developer.yahoo.com/yui/compressor/
.. _`Slim It`: http://slimit.org/
#. mimetype .. attribute:: COMPRESS_PRECOMPILERS
The mimetype of the file or inline code should that should be compiled.
#. command :Default: ``()``
The command to call on each of the files. Modern Python string
formatting will be provided for the two placeholders ``{infile}`` and
``{outfile}`` whose existence in the command string also triggers the
actual creation of those temporary files. If not given in the command
string, Django Compressor will use ``stdin`` and ``stdout`` respectively
instead.
Example:: An iterable of two-tuples whose first item is the mimetype of the files or
hunks you want to compile with the command specified as the second item:
COMPRESS_PRECOMPILERS = ( #. mimetype
('text/coffeescript', 'coffee --compile --stdio'), The mimetype of the file or inline code should that should be compiled.
('text/less', 'lessc {infile} {outfile}'),
('text/x-sass', 'sass {infile} {outfile}'),
('text/x-scss', 'sass --scss {infile} {outfile}'),
)
With that setting (and CoffeeScript_ installed), you could add the following #. command
code to your templates: The command to call on each of the files. Modern Python string
formatting will be provided for the two placeholders ``{infile}`` and
``{outfile}`` whose existence in the command string also triggers the
actual creation of those temporary files. If not given in the command
string, Django Compressor will use ``stdin`` and ``stdout`` respectively
instead.
.. code-block:: django Example::
{% load compress %} COMPRESS_PRECOMPILERS = (
('text/coffeescript', 'coffee --compile --stdio'),
('text/less', 'lessc {infile} {outfile}'),
('text/x-sass', 'sass {infile} {outfile}'),
('text/x-scss', 'sass --scss {infile} {outfile}'),
)
{% compress js %} With that setting (and CoffeeScript_ installed), you could add the following
<script type="text/coffeescript" charset="utf-8" src="/static/js/awesome.coffee" /> code to your templates:
<script type="text/coffeescript" charset="utf-8">
# Functions:
square = (x) -> x * x
</script>
{% endcompress %}
This would give you something like this:: .. code-block:: django
<script type="text/javascript" src="/static/CACHE/js/8dd1a2872443.js" charset="utf-8"></script> {% load compress %}
The same works for less_, too: {% compress js %}
<script type="text/coffeescript" charset="utf-8" src="/static/js/awesome.coffee" />
<script type="text/coffeescript" charset="utf-8">
# Functions:
square = (x) -> x * x
</script>
{% endcompress %}
.. code-block:: django This would give you something like this::
{% load compress %} <script type="text/javascript" src="/static/CACHE/js/8dd1a2872443.js" charset="utf-8"></script>
{% compress css %} The same works for less_, too:
<link type="text/less" rel="stylesheet" href="/static/css/styles.less" charset="utf-8">
<style type="text/less">
@color: #4D926F;
#header { .. code-block:: django
color: @color;
}
</style>
{% endcompress %}
Which would be rendered something like:: {% load compress %}
<link rel="stylesheet" href="/static/CACHE/css/8ccf8d877f18.css" type="text/css" charset="utf-8"> {% compress css %}
<link type="text/less" rel="stylesheet" href="/static/css/styles.less" charset="utf-8">
<style type="text/less">
@color: #4D926F;
.. _less: http://lesscss.org/ #header {
.. _CoffeeScript: http://jashkenas.github.com/coffee-script/ color: @color;
}
</style>
{% endcompress %}
.. _compress_storage: Which would be rendered something like::
COMPRESS_STORAGE <link rel="stylesheet" href="/static/CACHE/css/8ccf8d877f18.css" type="text/css" charset="utf-8">
^^^^^^^^^^^^^^^^
:Default: ``'compressor.storage.CompressorFileStorage'`` .. _less: http://lesscss.org/
.. _CoffeeScript: http://jashkenas.github.com/coffee-script/
The dotted path to a Django Storage backend to be used to save the .. attribute:: COMPRESS_STORAGE
compressed files.
Django Compressor ships with one additional storage backend: :Default: ``'compressor.storage.CompressorFileStorage'``
* ``'compressor.storage.GzipCompressorFileStorage'`` The dotted path to a Django Storage backend to be used to save the
compressed files.
A subclass of the default storage backend, which will additionally Django Compressor ships with one additional storage backend:
create ``*.gz`` files of each of the compressed files.
.. _compress_parser: * ``'compressor.storage.GzipCompressorFileStorage'``
COMPRESS_PARSER A subclass of the default storage backend, which will additionally
^^^^^^^^^^^^^^^ create ``*.gz`` files of each of the compressed files.
:Default: ``'compressor.parser.AutoSelectParser'`` .. attribute:: COMPRESS_PARSER
The backend to use when parsing the JavaScript or Stylesheet files. The :Default: ``'compressor.parser.AutoSelectParser'``
``AutoSelectParser`` picks the ``lxml`` based parser when available, and falls
back to ``HtmlParser`` if ``lxml`` is not available.
``LxmlParser`` is the fastest available parser, but ``HtmlParser`` is not much The backend to use when parsing the JavaScript or Stylesheet files. The
slower. ``AutoSelectParser`` adds a slight overhead, but in most cases it ``AutoSelectParser`` picks the ``lxml`` based parser when available, and falls
won't be necessary to change the default parser. back to ``HtmlParser`` if ``lxml`` is not available.
The other two included parsers are considerably slower and should only be ``LxmlParser`` is the fastest available parser, but ``HtmlParser`` is not much
used if absolutely necessary. slower. ``AutoSelectParser`` adds a slight overhead, but in most cases it
won't be necessary to change the default parser.
.. warning:: The other two included parsers are considerably slower and should only be
used if absolutely necessary.
In some cases the ``compressor.parser.HtmlParser`` parser isn't able to .. warning::
parse invalid HTML in JavaScript or CSS content. As a workaround you
should use one of the more forgiving parsers, e.g. the
``BeautifulSoupParser``.
The backends included in Django Compressor: In some cases the ``compressor.parser.HtmlParser`` parser isn't able to
parse invalid HTML in JavaScript or CSS content. As a workaround you
should use one of the more forgiving parsers, e.g. the
``BeautifulSoupParser``.
- ``compressor.parser.AutoSelectParser`` The backends included in Django Compressor:
- ``compressor.parser.LxmlParser``
- ``compressor.parser.HtmlParser``
- ``compressor.parser.BeautifulSoupParser``
- ``compressor.parser.Html5LibParser``
See :ref:`dependencies` for more info about the packages you need - ``compressor.parser.AutoSelectParser``
for each parser. - ``compressor.parser.LxmlParser``
- ``compressor.parser.HtmlParser``
- ``compressor.parser.BeautifulSoupParser``
- ``compressor.parser.Html5LibParser``
.. _compress_cache_backend: See :ref:`dependencies` for more info about the packages you need
for each parser.
COMPRESS_CACHE_BACKEND Caching settings
^^^^^^^^^^^^^^^^^^^^^^ ----------------
:Default: ``"default"`` or ``CACHE_BACKEND`` .. attribute:: COMPRESS_CACHE_BACKEND
The backend to use for caching, in case you want to use a different cache :Default: ``"default"`` or ``CACHE_BACKEND``
backend for Django Compressor.
If you have set the ``CACHES`` setting (new in Django 1.3), The backend to use for caching, in case you want to use a different cache
``COMPRESS_CACHE_BACKEND`` defaults to ``"default"``, which is the alias for backend for Django Compressor.
the default cache backend. You can set it to a different alias that you have
configured in your ``CACHES`` setting.
If you have not set ``CACHES`` and are using the old ``CACHE_BACKEND`` If you have set the ``CACHES`` setting (new in Django 1.3),
setting, ``COMPRESS_CACHE_BACKEND`` defaults to the ``CACHE_BACKEND`` setting. ``COMPRESS_CACHE_BACKEND`` defaults to ``"default"``, which is the alias for
the default cache backend. You can set it to a different alias that you have
configured in your ``CACHES`` setting.
COMPRESS_REBUILD_TIMEOUT If you have not set ``CACHES`` and are using the old ``CACHE_BACKEND``
^^^^^^^^^^^^^^^^^^^^^^^^ setting, ``COMPRESS_CACHE_BACKEND`` defaults to the ``CACHE_BACKEND`` setting.
:Default: ``2592000`` (30 days in seconds) .. attribute:: COMPRESS_REBUILD_TIMEOUT
The period of time after which the compressed files are rebuilt even if :Default: ``2592000`` (30 days in seconds)
no file changes are detected.
COMPRESS_MINT_DELAY The period of time after which the compressed files are rebuilt even if
^^^^^^^^^^^^^^^^^^^ no file changes are detected.
:Default: ``30`` (seconds) .. attribute:: COMPRESS_MINT_DELAY
The upper bound on how long any compression should take to run. Prevents :Default: ``30`` (seconds)
dog piling, should be a lot smaller than COMPRESS_REBUILD_TIMEOUT_.
COMPRESS_MTIME_DELAY The upper bound on how long any compression should take to run. Prevents
^^^^^^^^^^^^^^^^^^^^ dog piling, should be a lot smaller than
:attr:`~django.conf.settings.COMPRESS_REBUILD_TIMEOUT`.
:Default: ``10`` .. attribute:: COMPRESS_MTIME_DELAY
The amount of time (in seconds) to cache the modification timestamp of a :Default: ``10``
file. Disabled by default. Should be smaller than COMPRESS_REBUILD_TIMEOUT_
and COMPRESS_MINT_DELAY_.
COMPRESS_DEBUG_TOGGLE The amount of time (in seconds) to cache the modification timestamp of a
^^^^^^^^^^^^^^^^^^^^^ file. Disabled by default. Should be smaller than
:attr:`django.conf.settings.COMPRESS_REBUILD_TIMEOUT` and
:attr:`django.conf.settings.COMPRESS_MINT_DELAY`.
:Default: None .. attribute:: COMPRESS_DEBUG_TOGGLE
The name of the GET variable that toggles the debug mode and prevents Django :Default: None
Compressor from performing the actual compression. Only useful for debugging.
.. warning:: The name of the GET variable that toggles the debug mode and prevents Django
Compressor from performing the actual compression. Only useful for debugging.
Don't use this option in production! .. warning::
An easy convention is to only set it depending on the ``DEBUG`` setting:: Don't use this option in production!
if DEBUG: An easy convention is to only set it depending on the ``DEBUG`` setting::
COMPRESS_DEBUG_TOGGLE = 'whatever'
.. note:: if DEBUG:
COMPRESS_DEBUG_TOGGLE = 'whatever'
This only works for pages that are rendered using the RequestContext_ .. note::
and the ``django.core.context_processors.request`` context processor.
.. _RequestContext: http://docs.djangoproject.com/en/dev/ref/templates/api/#django.template.RequestContext This only works for pages that are rendered using the RequestContext_
and the ``django.core.context_processors.request`` context processor.
.. _compress_offline: .. _RequestContext: http://docs.djangoproject.com/en/dev/ref/templates/api/#django.template.RequestContext
COMPRESS_OFFLINE Offline settings
^^^^^^^^^^^^^^^^ ----------------
:Default: ``False`` .. attribute:: COMPRESS_OFFLINE
Boolean that decides if compression should also be done outside of the :Default: ``False``
request/response loop -- independent from user requests. This allows to
pre-compress CSS and JavaScript files and works just like the automatic
compression with the ``{% compress %}`` tag.
.. _compress_offline_timeout: Boolean that decides if compression should also be done outside of the
request/response loop -- independent from user requests. This allows to
pre-compress CSS and JavaScript files and works just like the automatic
compression with the ``{% compress %}`` tag.
COMPRESS_OFFLINE_TIMEOUT .. attribute:: COMPRESS_OFFLINE_TIMEOUT
^^^^^^^^^^^^^^^^^^^^^^^^
:Default: ``31536000`` (1 year in seconds) :Default: ``31536000`` (1 year in seconds)
The period of time with which the ``compress`` management command stores The period of time with which the ``compress`` management command stores
the pre-compressed the contents of ``{% compress %}`` template tags in the pre-compressed the contents of ``{% compress %}`` template tags in
the cache. the cache.
.. _compress_offline_context: .. attribute:: COMPRESS_OFFLINE_CONTEXT
COMPRESS_OFFLINE_CONTEXT :Default: ``{'MEDIA_URL': settings.MEDIA_URL}``
^^^^^^^^^^^^^^^^^^^^^^^^
:Default: ``{'MEDIA_URL': settings.MEDIA_URL}`` The context to be used by the ``compress`` management command when rendering
the contents of ``{% compress %}`` template tags and saving the result in the
offline cache.
The context to be used by the ``compress`` management command when rendering If available, the ``STATIC_URL`` setting is also added to the context.
the contents of ``{% compress %}`` template tags and saving the result in the
offline cache.
If available, the ``STATIC_URL`` setting is also added to the context. .. attribute:: COMPRESS_OFFLINE_MANIFEST
.. _compress_offline_manifest: :Default: ``manifest.json``
COMPRESS_OFFLINE_MANIFEST The name of the file to be used for saving the names of the files compressed
^^^^^^^^^^^^^^^^^^^^^^^^^ offline.
:Default: ``manifest.json``
The name of the file to be used for saving the names of the files compressed
offline.

27
docs/usage.txt
View File

@@ -46,21 +46,24 @@ Which would be rendered something like:
<script type="text/javascript" src="/static/CACHE/js/3f33b9146e12.js" charset="utf-8"></script> <script type="text/javascript" src="/static/CACHE/js/3f33b9146e12.js" charset="utf-8"></script>
Linked files **must** be accessible via :ref:`COMPRESS_URL <compress_url>`. Linked files **must** be accessible via
:attr:`~django.conf.settings.COMPRESS_URL`.
If the :ref:`COMPRESS_ENABLED <compress_enabled>` setting is ``False`` If the :attr:`~django.conf.settings.COMPRESS_ENABLED` setting is ``False``
(defaults to the opposite of DEBUG) the ``compress`` template tag does nothing (defaults to the opposite of DEBUG) the ``compress`` template tag does nothing
and simply returns exactly what it was given. and simply returns exactly what it was given.
.. note:: .. note::
If you've configured any :ref:`precompilers <compress_precompilers>` If you've configured any
setting :ref:`COMPRESS_ENABLED <compress_enabled>` to ``False`` won't :attr:`precompilers <django.conf.settings.COMPRESS_PRECOMPILERS>`
setting :attr:`~django.conf.settings.COMPRESS_ENABLED` to ``False`` won't
affect the processing of those files. Only the affect the processing of those files. Only the
:ref:`CSS <compress_css_filters>` and :attr:`CSS <django.conf.settings.COMPRESS_CSS_FILTERS>` and
:ref:`JavaScript filters <compress_js_filters>` will be disabled. :attr:`JavaScript filters <django.conf.settings.COMPRESS_JS_FILTERS>`
will be disabled.
If both DEBUG and :ref:`COMPRESS_ENABLED <compress_enabled>` are set to If both DEBUG and :attr:`~django.conf.settings.COMPRESS_ENABLED` are set to
``True``, incompressible files (off-site or non existent) will throw an ``True``, incompressible files (off-site or non existent) will throw an
exception. If DEBUG is ``False`` these files will be silently stripped. exception. If DEBUG is ``False`` these files will be silently stripped.
@@ -69,7 +72,7 @@ exception. If DEBUG is ``False`` these files will be silently stripped.
For production sites it is **strongly recommended** to use a real cache For production sites it is **strongly recommended** to use a real cache
backend such as memcached_ to speed up the checks of compressed files. backend such as memcached_ to speed up the checks of compressed files.
Make sure you set your Django cache backend appropriately (also see Make sure you set your Django cache backend appropriately (also see
:ref:`COMPRESS_CACHE_BACKEND <compress_cache_backend>` and :attr:`~django.conf.settings.COMPRESS_CACHE_BACKEND` and
Django's `caching documentation`_). Django's `caching documentation`_).
The compress template tag supports a second argument specifying the output The compress template tag supports a second argument specifying the output
@@ -112,7 +115,7 @@ works just like the automatic compression with the ``{% compress %}`` tag.
To compress the files "offline" and update the offline cache you have To compress the files "offline" and update the offline cache you have
to use the ``compress`` management command, ideally during deployment. to use the ``compress`` management command, ideally during deployment.
Also make sure to enable the :ref:`COMPRESS_OFFLINE <compress_offline>` Also make sure to enable the :attr:`django.conf.settings.COMPRESS_OFFLINE`
setting. In case you don't use the ``compress`` management command, Django setting. In case you don't use the ``compress`` management command, Django
Compressor will automatically fallback to the automatic compression using Compressor will automatically fallback to the automatic compression using
the template tag. the template tag.
@@ -120,7 +123,7 @@ the template tag.
The command parses all templates that can be found with the template The command parses all templates that can be found with the template
loader (as specified in the TEMPLATE_LOADERS_ setting) and looks for loader (as specified in the TEMPLATE_LOADERS_ setting) and looks for
``{% compress %}`` blocks. It then will use the context as defined in ``{% compress %}`` blocks. It then will use the context as defined in
:ref:`COMPRESS_OFFLINE_CONTEXT <compress_offline_context>` to render its :attr:`django.conf.settings.COMPRESS_OFFLINE_CONTEXT` to render its
content. So if you use any variables inside the ``{% compress %}`` blocks, content. So if you use any variables inside the ``{% compress %}`` blocks,
make sure to list all values you require in ``COMPRESS_OFFLINE_CONTEXT``. make sure to list all values you require in ``COMPRESS_OFFLINE_CONTEXT``.
It's similar to a template context and should be used if a variable is used It's similar to a template context and should be used if a variable is used
@@ -146,8 +149,8 @@ the commonly used setting to refer to saved files ``MEDIA_URL`` and
``STATIC_URL`` (if specified in the settings). ``STATIC_URL`` (if specified in the settings).
The result of running the ``compress`` management command will be cached The result of running the ``compress`` management command will be cached
in a file called ``manifest.json`` using the :ref:`configured storage in a file called ``manifest.json`` using the :attr:`configured storage
<compress_storage>` to be able to be transfered from your developement <django.conf.settings.COMPRESS_STORAGE>` to be able to be transfered from your developement
computer to the server easily. computer to the server easily.
.. _TEMPLATE_LOADERS: http://docs.djangoproject.com/en/dev/ref/settings/#template-loaders .. _TEMPLATE_LOADERS: http://docs.djangoproject.com/en/dev/ref/settings/#template-loaders