diff --git a/docs/changelog.txt b/docs/changelog.txt index d67639f..8b7848f 100644 --- a/docs/changelog.txt +++ b/docs/changelog.txt @@ -79,8 +79,8 @@ v1.1 manifest.json file). You can now easily run the :ref:`compress ` management - command locally and transfer the :ref:`COMPRESS_ROOT ` dir - to your server. + command locally and transfer the :attr:`~django.conf.settings.COMPRESS_ROOT` + dir to your server. - Updated installation instructions to properly mention all dependencies, 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 hunks with easily configurable compilers before calling the actual output filters. See the - :ref:`COMPRESS_PRECOMPILERS ` for more details. + :attr:`~django.conf.settings.COMPRESS_PRECOMPILERS` for more details. - New staticfiles support. With the introduction of the staticfiles app 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. - Deprecated ``COMPRESS_LESSC_BINARY`` setting because it's now - superseded by the :ref:`COMPRESS_PRECOMPILERS ` + superseded by the :attr:`~django.conf.settings.COMPRESS_PRECOMPILERS` 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:: diff --git a/docs/index.txt b/docs/index.txt index d849f47..671dfd9 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -33,7 +33,7 @@ Contents ======== .. toctree:: - :maxdepth: 1 + :maxdepth: 2 installation usage diff --git a/docs/installation.txt b/docs/installation.txt index ed6cca7..a71bf91 100644 --- a/docs/installation.txt +++ b/docs/installation.txt @@ -1,5 +1,8 @@ +Quickstart +========== + Installation -============ +------------ * 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 counterpart django-staticfiles_) you have to add Django Compressor's file finder to the ``STATICFILES_FINDERS`` setting, for example with - ``django.contrib.staticfiles``:: + ``django.contrib.staticfiles``: - STATICFILES_FINDERS = ( - 'django.contrib.staticfiles.finders.FileSystemFinder', - 'django.contrib.staticfiles.finders.AppDirectoriesFinder', - # other finders.. - 'compressor.finders.CompressorFinder', - ) + .. code-block:: python + + STATICFILES_FINDERS = ( + 'django.contrib.staticfiles.finders.FileSystemFinder', + 'django.contrib.staticfiles.finders.AppDirectoriesFinder', + # other finders.. + 'compressor.finders.CompressorFinder', + ) .. _staticfiles: http://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/ .. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles @@ -35,59 +40,63 @@ Installation Dependencies ------------ -django-appconf_ (required) -^^^^^^^^^^^^^^^^^^^^^^^^^^ +Required +^^^^^^^^ -Used internally to handle Django's settings, this is -automatically installed when following the above -installation instructions. In case you're installing -Django Compressor differently, make sure to install -it, e.g.:: +In case you're installing Django Compressor differently +(e.g. from the Git repo), make sure to install the following +dependencies. - 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 -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 django-appconf - 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 ` -``compressor.parser.BeautifulSoupParser`` and -``compressor.parser.LxmlParser``:: + In case you're installing Django Compressor differently + (e.g. from the Git repo), make sure to install it, e.g.:: - pip install BeautifulSoup<=4.0 + pip install versiontools -lxml_ (optional) -^^^^^^^^^^^^^^^^ +Optional +^^^^^^^^ -for the :ref:`parser ` ``compressor.parser.LxmlParser``, -also requires libxml2_:: +- BeautifulSoup_ - STATIC_DEPS=true pip install lxml + For the :attr:`parser ` + ``compressor.parser.BeautifulSoupParser`` and + ``compressor.parser.LxmlParser``:: -html5lib_ (optional) -^^^^^^^^^^^^^^^^^^^^ + pip install BeautifulSoup<=4.0 -for the :ref:`parser ` ``compressor.parser.Html5LibParser``:: +- lxml_ - pip install html5lib + For the :attr:`parser ` + ``compressor.parser.LxmlParser``, also requires libxml2_:: -`Slim It`_ (optional) -^^^^^^^^^^^^^^^^^^^^^ + STATIC_DEPS=true pip install lxml -for the :ref:`Slim It filter ` ``compressor.filters.jsmin.SlimItFilter``:: +- html5lib_ - pip install slimit + For the :attr:`parser ` + ``compressor.parser.Html5LibParser``:: + pip install html5lib + +- `Slim It`_ + + For the :ref:`Slim It filter ` + ``compressor.filters.jsmin.SlimItFilter``:: + + pip install slimit .. _BeautifulSoup: http://www.crummy.com/software/BeautifulSoup/ .. _lxml: http://codespeak.net/lxml/ diff --git a/docs/remote-storages.txt b/docs/remote-storages.txt index 9e20233..83458fe 100644 --- a/docs/remote-storages.txt +++ b/docs/remote-storages.txt @@ -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. Django Compressor provides hooks to automatically have compressed files -pushed to a remote storage backend. Simply -:ref:`set the storage backend ` that saves the result to a -remote service. +pushed to a remote storage backend. Simply set the storage backend +that saves the result to a remote service (see +:attr:`~django.conf.settings.COMPRESS_STORAGE`). + +django-storages +^^^^^^^^^^^^^^^ 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:: @@ -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 integrated. -#. Make sure the :ref:`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 when to do their job. @@ -68,13 +71,14 @@ integrated. self.local_storage._save(name, content) return name -#. Set your :ref:`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. ``'mysite.storage.CachedS3BotoStorage'``. #. To have Django correctly render the URLs to your static files, set the - STATIC_URL_ setting to the same value as :ref:`COMPRESS_URL ` - (e.g. ``"http://compressor-test.s3.amazon.com/"``). + STATIC_URL_ setting to the same value as + :attr:`~django.conf.settings.COMPRESS_URL` (e.g. + ``"http://compressor-test.s3.amazon.com/"``). .. _CDN: http://en.wikipedia.org/wiki/Content_delivery_network .. _Amazon S3: https://s3.amazonaws.com/ diff --git a/docs/settings.txt b/docs/settings.txt index db39c57..2316c89 100644 --- a/docs/settings.txt +++ b/docs/settings.txt @@ -1,424 +1,410 @@ .. _settings: Settings --------- +======== + +.. currentmodule:: django.conf.settings Django Compressor has a number of settings that control its behavior. 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 -when ``DEBUG`` is ``True`` COMPRESS_ENABLED_ must also be set to ``True``. + Boolean that decides if compression will happen. To test compression + when ``DEBUG`` is ``True`` ``COMPRESS_ENABLED`` must also be set to + ``True``. -When COMPRESS_ENABLED_ is ``False`` the input will be rendered without any -compression except for code with a mimetype matching one listed in the -COMPRESS_PRECOMPILERS_ setting. These matching files are still passed to the -precompiler before rendering. + When ``COMPRESS_ENABLED`` is ``False`` the input will be rendered without + any compression except for code with a mimetype matching one listed in the + :attr:`~django.conf.settings.COMPRESS_PRECOMPILERS` setting. These + 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 %} - - + + +.. 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 -will be written to. +.. attribute:: COMPRESS_ROOT -.. note:: + :Default: ``STATIC_ROOT`` (``MEDIA_ROOT`` 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 absolute file path that linked static will be read from and + 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 -compressed static will be written to when using the default COMPRESS_STORAGE_ -``compressor.storage.CompressorFileStorage``. + :Default: ``'CACHE'`` -.. 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`` - is not given, e.g. on older Django versions (<1.3). +Backend settings +---------------- -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 -be written to. + A list of filters that will be applied to CSS. -.. _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 - 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. + .. attribute:: COMPRESS_CSSTIDY_BINARY -``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 - this value will be embedded. In bytes. + Only files that are smaller than this in bytes value will be embedded. -``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 - to also prepend this setting with ``java -jar`` if you use that kind of - distribution. + .. attribute:: COMPRESS_YUI_BINARY -- ``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 -algorithm cssmin_. + The arguments passed to the compressor. -.. _CSSTidy: http://csstidy.sourceforge.net/ -.. _`data: URIs`: http://en.wikipedia.org/wiki/Data_URI_scheme -.. _cssmin: http://pypi.python.org/pypi/cssmin/ + - ``compressor.filters.cssmin.CSSMinFilter`` + + 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 -^^^^^^^^^^^^^^^^^^^ +.. 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 - path. Make sure to also prepend this setting with ``java -jar`` if you - use that kind of distribution. + A filter that uses `Google Closure compiler`_. + + .. 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/ -.. _`Google Closure compiler`: http://code.google.com/closure/compiler/ -.. _`YUI compressor`: http://developer.yahoo.com/yui/compressor/ -.. _`Slim It`: http://slimit.org/ + .. attribute:: COMPRESS_YUI_BINARY -.. _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 -hunks you want to compile with the command specified as the second item: + .. _rJSmin: http://opensource.perlig.de/rjsmin/ + .. _`Google Closure compiler`: http://code.google.com/closure/compiler/ + .. _`YUI compressor`: http://developer.yahoo.com/yui/compressor/ + .. _`Slim It`: http://slimit.org/ -#. mimetype - The mimetype of the file or inline code should that should be compiled. +.. attribute:: COMPRESS_PRECOMPILERS -#. command - 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. + :Default: ``()`` -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 = ( - ('text/coffeescript', 'coffee --compile --stdio'), - ('text/less', 'lessc {infile} {outfile}'), - ('text/x-sass', 'sass {infile} {outfile}'), - ('text/x-scss', 'sass --scss {infile} {outfile}'), - ) + #. mimetype + The mimetype of the file or inline code should that should be compiled. -With that setting (and CoffeeScript_ installed), you could add the following -code to your templates: + #. command + 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 %} - - {% endcompress %} + With that setting (and CoffeeScript_ installed), you could add the following + code to your templates: -This would give you something like this:: + .. code-block:: django - + {% load compress %} -The same works for less_, too: + {% compress js %} + + {% endcompress %} -.. code-block:: django + This would give you something like this:: - {% load compress %} + - {% compress css %} - - - {% endcompress %} + .. code-block:: django -Which would be rendered something like:: + {% load compress %} - + {% compress css %} + + + {% endcompress %} -.. _compress_storage: + Which would be rendered something like:: -COMPRESS_STORAGE -^^^^^^^^^^^^^^^^ + -: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 -compressed files. +.. attribute:: COMPRESS_STORAGE -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 - create ``*.gz`` files of each of the compressed files. + Django Compressor ships with one additional storage backend: -.. _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 -``AutoSelectParser`` picks the ``lxml`` based parser when available, and falls -back to ``HtmlParser`` if ``lxml`` is not available. + :Default: ``'compressor.parser.AutoSelectParser'`` -``LxmlParser`` is the fastest available parser, but ``HtmlParser`` is not much -slower. ``AutoSelectParser`` adds a slight overhead, but in most cases it -won't be necessary to change the default parser. + The backend to use when parsing the JavaScript or Stylesheet files. The + ``AutoSelectParser`` picks the ``lxml`` based parser when available, and falls + back to ``HtmlParser`` if ``lxml`` is not available. -The other two included parsers are considerably slower and should only be -used if absolutely necessary. + ``LxmlParser`` is the fastest available parser, but ``HtmlParser`` is not much + 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 - parse invalid HTML in JavaScript or CSS content. As a workaround you - should use one of the more forgiving parsers, e.g. the - ``BeautifulSoupParser``. + .. warning:: -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`` -- ``compressor.parser.LxmlParser`` -- ``compressor.parser.HtmlParser`` -- ``compressor.parser.BeautifulSoupParser`` -- ``compressor.parser.Html5LibParser`` + The backends included in Django Compressor: -See :ref:`dependencies` for more info about the packages you need -for each parser. + - ``compressor.parser.AutoSelectParser`` + - ``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 -backend for Django Compressor. + :Default: ``"default"`` or ``CACHE_BACKEND`` -If you have set the ``CACHES`` setting (new in Django 1.3), -``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. + The backend to use for caching, in case you want to use a different cache + backend for Django Compressor. -If you have not set ``CACHES`` and are using the old ``CACHE_BACKEND`` -setting, ``COMPRESS_CACHE_BACKEND`` defaults to the ``CACHE_BACKEND`` setting. + If you have set the ``CACHES`` setting (new in Django 1.3), + ``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 -no file changes are detected. + :Default: ``2592000`` (30 days in seconds) -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 -dog piling, should be a lot smaller than COMPRESS_REBUILD_TIMEOUT_. + :Default: ``30`` (seconds) -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 -file. Disabled by default. Should be smaller than COMPRESS_REBUILD_TIMEOUT_ -and COMPRESS_MINT_DELAY_. + :Default: ``10`` -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 -Compressor from performing the actual compression. Only useful for debugging. + :Default: None -.. 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: - COMPRESS_DEBUG_TOGGLE = 'whatever' + An easy convention is to only set it depending on the ``DEBUG`` setting:: -.. note:: + if DEBUG: + COMPRESS_DEBUG_TOGGLE = 'whatever' - This only works for pages that are rendered using the RequestContext_ - and the ``django.core.context_processors.request`` context processor. + .. note:: -.. _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 -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. + :Default: ``False`` -.. _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 pre-compressed the contents of ``{% compress %}`` template tags in -the cache. + The period of time with which the ``compress`` management command stores + the pre-compressed the contents of ``{% compress %}`` template tags in + 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 -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. -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 -^^^^^^^^^^^^^^^^^^^^^^^^^ - -:Default: ``manifest.json`` - -The name of the file to be used for saving the names of the files compressed -offline. + The name of the file to be used for saving the names of the files compressed + offline. diff --git a/docs/usage.txt b/docs/usage.txt index 9376345..41f0aeb 100644 --- a/docs/usage.txt +++ b/docs/usage.txt @@ -46,21 +46,24 @@ Which would be rendered something like: -Linked files **must** be accessible via :ref:`COMPRESS_URL `. +Linked files **must** be accessible via +:attr:`~django.conf.settings.COMPRESS_URL`. -If the :ref:`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 and simply returns exactly what it was given. .. note:: - If you've configured any :ref:`precompilers ` - setting :ref:`COMPRESS_ENABLED ` to ``False`` won't + If you've configured any + :attr:`precompilers ` + setting :attr:`~django.conf.settings.COMPRESS_ENABLED` to ``False`` won't affect the processing of those files. Only the - :ref:`CSS ` and - :ref:`JavaScript filters ` will be disabled. + :attr:`CSS ` and + :attr:`JavaScript filters ` + will be disabled. -If both DEBUG and :ref:`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 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 backend such as memcached_ to speed up the checks of compressed files. Make sure you set your Django cache backend appropriately (also see - :ref:`COMPRESS_CACHE_BACKEND ` and + :attr:`~django.conf.settings.COMPRESS_CACHE_BACKEND` and Django's `caching documentation`_). 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 use the ``compress`` management command, ideally during deployment. -Also make sure to enable the :ref:`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 Compressor will automatically fallback to the automatic compression using the template tag. @@ -120,7 +123,7 @@ the template tag. The command parses all templates that can be found with the template loader (as specified in the TEMPLATE_LOADERS_ setting) and looks for ``{% compress %}`` blocks. It then will use the context as defined in -:ref:`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, 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 @@ -146,8 +149,8 @@ the commonly used setting to refer to saved files ``MEDIA_URL`` and ``STATIC_URL`` (if specified in the settings). The result of running the ``compress`` management command will be cached -in a file called ``manifest.json`` using the :ref:`configured storage -` to be able to be transfered from your developement +in a file called ``manifest.json`` using the :attr:`configured storage +` to be able to be transfered from your developement computer to the server easily. .. _TEMPLATE_LOADERS: http://docs.djangoproject.com/en/dev/ref/settings/#template-loaders