From b95bac9970c33ac30eb6b5ed0c77e86a84e03ccb Mon Sep 17 00:00:00 2001 From: Jannis Leidel Date: Fri, 8 Apr 2011 19:15:30 +0200 Subject: [PATCH] Split documentation in pieces to be easier to read. --- docs/behind-the-scenes.txt | 47 ++++ docs/index.txt | 508 +------------------------------------ docs/installation.txt | 68 +++++ docs/remote-storages.txt | 84 ++++++ docs/settings.txt | 284 +++++++++++++++++++++ docs/usage.txt | 87 +++++++ setup.py | 2 +- 7 files changed, 584 insertions(+), 496 deletions(-) create mode 100644 docs/behind-the-scenes.txt create mode 100644 docs/installation.txt create mode 100644 docs/remote-storages.txt create mode 100644 docs/settings.txt create mode 100644 docs/usage.txt diff --git a/docs/behind-the-scenes.txt b/docs/behind-the-scenes.txt new file mode 100644 index 000000000..62b431531 --- /dev/null +++ b/docs/behind-the-scenes.txt @@ -0,0 +1,47 @@ +Behind the scenes +================= + +This document assumes you already have an up and running instance of +Django Compressor, and that you understand how to use it in your templates. +The goal is to explain what the main template tag, {% compress %}, does +behind the scenes, to help you debug performance problems for instance. + +First step: Offline cache +------------------------- + +The first thing {% compress %} tries to do is get the offline cache for its +nodelist if offline cache is activated. It doesn't parse, doesn't check the +modified times of the files, doesn't 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 cache should return the HTML +containing the element code for the combined file or piece of code (which, +if the cache key exists, is supposed to already exist on disk/custom storage). + +Everything stops here if the cache entry exists. + +Second step: parsing and file list +---------------------------------- + +A compressor instance is created, which in turns instanciates the HTML parser. +The parser is used to determine a file or code hunk list. Each file mtime is +checked, first in cache and then on disk/storage, and this is used to +determine an unique cache key. + +Third step: Checking the "main" cache +------------------------------------- + +Compressor checks if it can get some info about the combined file/hunks +corresponding to its instance, using the cache key obtained in the previous +step. The cache content here will actually be the HTML containing the final +element code, just like in the offline step before. + +Everything stops here if the cache entry exists. + +Fourth step: Generating the combined file if needed +--------------------------------------------------- + +The file is generated if necessary. All precompilers are called and all +filters are executed, and a hash is determined from the contents. This in +turns helps determine the file name, which is only saved if it didn't exist +already. Then the HTML output is returned (and also saved in the cache). +And that's it! diff --git a/docs/index.txt b/docs/index.txt index db38e7dc9..0add7dafc 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -1,203 +1,9 @@ -Django compressor +================= +Django Compressor ================= Compresses linked and inline JavaScript or CSS into a single cached file. -Installation ------------- - -* Install django_compressor with your favorite Python package manager:: - - pip install django_compressor - -* Add ``'compressor'`` to your ``INSTALLED_APPS`` setting:: - - INSTALLED_APPS = ( - # other apps - "compressor", - ) - -* See the list of settings_ to modify django_compressor's default behaviour. - -* In case you use Django 1.3's staticfiles_ contrib app (or its standalone - clone django-staticfiles_) you have to add django_compressor's file finder - to the ``STATICFILES_FINDERS`` setting:: - - STATICFILES_FINDERS = ( - # other finders.. - 'compressor.finders.CompressorFinder', - ) - -.. _staticfiles: http://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/ -.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles - -Usage ------ - -.. code-block:: django - - {% load compress %} - {% compress %} - - {% endcompress %} - -Examples -^^^^^^^^ - -.. code-block:: django - - {% load compress %} - - {% compress css %} - - - - {% endcompress %} - -Which would be rendered something like: - -.. code-block:: django - - - -or: - -.. code-block:: django - - {% load compress %} - - {% compress js %} - - - {% endcompress %} - -Which would be rendered something like: - -.. code-block:: django - - - -Linked files must be accesible via COMPRESS_URL_. If DEBUG is ``True``, -off-site files will throw exceptions. If DEBUG is ``False`` they will be -silently stripped. - -If COMPRESS is ``False`` (defaults to the opposite of DEBUG) the ``compress`` -template tag simply returns exactly what it was given, to ease development. - -.. warning:: - - 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 - COMPRESS_CACHE_BACKEND_ and Django's `caching documentation`_). - -.. _memcached: http://memcached.org/ -.. _caching documentation: http://docs.djangoproject.com/en/1.2/topics/cache/#memcached - -Remote storages ---------------- - -In some cases it's useful to use a CDN_ for serving static files such as -those generated by django_compressor. Due to the way django_compressor -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 use set the COMPRESS_STORAGE_ -setting to a storage backend that saves the result to a remote service. - -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:: - - AWS_ACCESS_KEY_ID = 'XXXXXXXXXXXXXXXXXXXXX' - AWS_SECRET_ACCESS_KEY = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' - AWS_STORAGE_BUCKET_NAME = 'compressor-test' - -Next, you need to specify the new CDN base URL and update the URLs to the -files in your templates which you want to compress:: - - COMPRESS_URL = "http://compressor-test.s3.amazon.com/" - -.. note:: - - For staticfiles just set ``STATIC_URL = COMPRESS_URL`` - -The storage backend to save the compressed files needs to be changed, too:: - - COMPRESS_STORAGE = 'storages.backends.s3boto.S3BotoStorage' - -staticfiles -^^^^^^^^^^^ - -If you are using Django 1.3's staticfiles_ contrib app or the standalone -app django-staticfiles_, you'll need to use a temporary filesystem cache -for django_compressor to know which files to compress. Since staticfiles -provides a management command to collect static files from various -locations which uses a storage backend, this is where both apps can be -integrated. - -First, make sure the COMPRESS_ROOT_ and STATIC_ROOT_ settings are equal -since both apps need to look at the same directories when to do their job. - -Secondly, you need to create a subclass of the remote storage backend -you want to use; below is an example of the boto S3 storage backend -from django-storages:: - - from django.core.files.storage import get_storage_class - from storages.backends.s3boto import S3BotoStorage - - class CachedS3BotoStorage(S3BotoStorage): - """ - S3 storage backend that saves the files locally, too. - """ - def __init__(self, *args, **kwargs): - super(CachedS3BotoStorage, self).__init__(*args, **kwargs) - self.local_storage = get_storage_class( - "compressor.storage.CompressorFileStorage")() - - def save(self, name, content): - name = super(CachedS3BotoStorage, self).save(name, content) - self.local_storage._save(name, content) - return name - -Set your 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 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/ -.. _boto: http://boto.cloudhackers.com/ -.. _django-storages: http://code.welldev.org/django-storages/ -.. _STATIC_ROOT: http://docs.djangoproject.com/en/dev/ref/settings/#std:setting-STATIC_ROOT -.. _STATICFILES_STORAGE: http://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/#std:setting-STATICFILES_STORAGE - -CSS Notes ---------- - -All relative ``url()`` bits specified in linked CSS files are automatically -converted to absolute URLs while being processed. Any local absolute URLs (those -starting with a ``'/'``) are left alone. - -Stylesheets that are ``@import``'d are not compressed into the main file. -They are left alone. - -If the media attribute is set on - {% endcompress %} - -Which would be rendered something like:: - - - -.. _less: http://lesscss.org/ -.. _CoffeeScript: http://jashkenas.github.com/coffee-script/ - -COMPRESS_STORAGE -^^^^^^^^^^^^^^^^ - -:Default: ``'compressor.storage.CompressorFileStorage'`` - -The dotted path to a Django Storage backend to be used to save the -compressed files. - -``compressor`` ships with one additional storage backend: - -* ``'compressor.storage.GzipCompressorFileStorage'`` - - A subclass of the default storage backend, which will additionally - create ``*.gz`` files of each of the compressed files. - -COMPRESS_PARSER -^^^^^^^^^^^^^^^ - -:Default: ``'compressor.parser.BeautifulSoupParser'`` - -The backend to use when parsing the JavaScript or Stylesheet files. -The backends included in ``compressor``: - -- ``compressor.parser.BeautifulSoupParser`` -- ``compressor.parser.LxmlParser`` - -See `Dependencies`_ for more info about the packages you need for each parser. - -COMPRESS_CACHE_BACKEND -^^^^^^^^^^^^^^^^^^^^^^ - -:Default: ``"default"`` or ``CACHE_BACKEND`` - -The backend to use for caching, in case you want to use a different cache -backend for compressor. - -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. - -If you have not set ``CACHES`` and are using the old ``CACHE_BACKEND`` -setting, ``COMPRESS_CACHE_BACKEND`` defaults to the ``CACHE_BACKEND`` setting. - -COMPRESS_REBUILD_TIMEOUT -^^^^^^^^^^^^^^^^^^^^^^^^ - -:Default: ``2592000`` (30 days in seconds) - -The period of time after which the compressed files are rebuilt even if -no file changes are detected. - -COMPRESS_MINT_DELAY -^^^^^^^^^^^^^^^^^^^ - -:Default: ``30`` (seconds) - -The upper bound on how long any compression should take to run. Prevents -dog piling, should be a lot smaller than COMPRESS_REBUILD_TIMEOUT_. - -COMPRESS_MTIME_DELAY -^^^^^^^^^^^^^^^^^^^^ - -:Default: ``10`` - -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_. - -COMPRESS_OFFLINE -^^^^^^^^^^^^^^^^ - -:Default: ``False`` - -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. - -To compress the files "offline" and update the offline cache you have -to use the ``compress`` management command, e.g. during deployment. -In case you don't use the ``compressor`` management command ``compressor`` -will automatically fallback to the automatic compression. - -It'll will look in the templates that can be found with the template -loader you specify in ``TEMPLATE_LOADERS`` for ``{% compress %}`` blocks -and use 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_. - -The result of running the ``compress`` management command will be saved -in the cache as defined in COMPRESS_CACHE_BACKEND_ for the number of -seconds defined in COMPRESS_OFFLINE_TIMEOUT_. - -COMPRESS_OFFLINE_TIMEOUT -^^^^^^^^^^^^^^^^^^^^^^^^ - -: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. - -COMPRESS_OFFLINE_CONTEXT -^^^^^^^^^^^^^^^^^^^^^^^^ - -: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. It's similar to a template context and should be used if a -variable is used in the blocks, e.g.: - -.. code-block:: django - - {% load compress %} - {% compress js %} - - {% endcompress %} - -Since this template requires a variable (``path_to_files``) you need to -specify this in your settings before using the ``compress`` management -command:: - - COMPRESS_OFFLINE_CONTEXT = { - 'path_to_files': '/static/js/', - } - -If not specified the COMPRESS_OFFLINE_CONTEXT will fall back to contain -the commonly used setting to refer to saved files ``MEDIA_URL``. - -For forward compatibility ``compressor`` will also add the ``STATIC_URL`` -setting (added in Django 1.3) to the COMPRESS_OFFLINE_CONTEXT_ if it's set. - -Dependencies ------------- - -* BeautifulSoup_ (for the default ``compressor.parser.BeautifulSoupParser``) - -:: - - pip install BeautifulSoup - -* lxml_ (for the optional ``compressor.parser.LxmlParser``, requires libxml2_) - -:: - - STATIC_DEPS=true pip install lxml - -.. _BeautifulSoup: http://www.crummy.com/software/BeautifulSoup/ -.. _lxml: http://codespeak.net/lxml/ -.. _libxml2: http://xmlsoft.org/ - -Deprecation ------------ +Contents +======== -This section lists features and settings that are deprecated or removed -in newer versions of django_compressor. +.. toctree:: + :maxdepth: 1 -* ``COMPRESS_LESSC_BINARY`` - Superseded by the 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:: + installation + usage + settings + remote-storages + behind-the-scenes - COMPRESS_PRECOMPILERS = ( - ('text/less', 'lessc {infile} {outfile}'), - ) diff --git a/docs/installation.txt b/docs/installation.txt new file mode 100644 index 000000000..117fb2619 --- /dev/null +++ b/docs/installation.txt @@ -0,0 +1,68 @@ +Installation +============ + +* Install Django Compressor with your favorite Python package manager:: + + pip install django_compressor + +* Add ``'compressor'`` to your ``INSTALLED_APPS`` setting:: + + INSTALLED_APPS = ( + # other apps + "compressor", + ) + +* See the list of :ref:`settings` to modify Django Compressor's + default behaviour and make adjustements for your website. + +* In case you use Django 1.3's staticfiles_ contrib app (or its standalone + clone django-staticfiles_) you have to add django_compressor's file finder + to the ``STATICFILES_FINDERS`` setting:: + + STATICFILES_FINDERS = ( + # other finders.. + 'compressor.finders.CompressorFinder', + ) + +.. _staticfiles: http://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/ +.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles + +.. _dependencies: + +Dependencies +------------ + +BeautifulSoup_ +^^^^^^^^^^^^^^ + +for the default :ref:`parser ` +``compressor.parser.BeautifulSoupParser``:: + + pip install BeautifulSoup + +lxml_ (optional) +^^^^^^^^^^^^^^^^ + +for the optional :ref:`parser ` +``compressor.parser.LxmlParser``, also requires libxml2_:: + + STATIC_DEPS=true pip install lxml + +.. _BeautifulSoup: http://www.crummy.com/software/BeautifulSoup/ +.. _lxml: http://codespeak.net/lxml/ +.. _libxml2: http://xmlsoft.org/ + +Deprecation +----------- + +This section lists features and settings that are deprecated or removed +in newer versions of Django Compressor. + +* ``COMPRESS_LESSC_BINARY`` + Superseded by the :ref:`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:: + + COMPRESS_PRECOMPILERS = ( + ('text/less', 'lessc {infile} {outfile}'), + ) diff --git a/docs/remote-storages.txt b/docs/remote-storages.txt new file mode 100644 index 000000000..0ae6a376f --- /dev/null +++ b/docs/remote-storages.txt @@ -0,0 +1,84 @@ +Remote storages +--------------- + +In some cases it's useful to use a CDN_ for serving static files such as +those generated by Django Compressor. Due to the way Django Compressor +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. + +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:: + + AWS_ACCESS_KEY_ID = 'XXXXXXXXXXXXXXXXXXXXX' + AWS_SECRET_ACCESS_KEY = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' + AWS_STORAGE_BUCKET_NAME = 'compressor-test' + +Next, you need to specify the new CDN base URL and update the URLs to the +files in your templates which you want to compress:: + + COMPRESS_URL = "http://compressor-test.s3.amazon.com/" + +.. note:: + + For staticfiles just set ``STATIC_URL = COMPRESS_URL`` + +The storage backend to save the compressed files needs to be changed, too:: + + COMPRESS_STORAGE = 'storages.backends.s3boto.S3BotoStorage' + +Using staticfiles +^^^^^^^^^^^^^^^^^ + +If you are using Django 1.3's staticfiles_ contrib app or the standalone +app django-staticfiles_, you'll need to use a temporary filesystem cache +for Django Compressor to know which files to compress. Since staticfiles +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_ + settings are equal since both apps need to look at the same directories + when to do their job. + +#. You need to create a subclass of the remote storage backend you want + to use; below is an example of the boto S3 storage backend from + django-storages_:: + + from django.core.files.storage import get_storage_class + from storages.backends.s3boto import S3BotoStorage + + class CachedS3BotoStorage(S3BotoStorage): + """ + S3 storage backend that saves the files locally, too. + """ + def __init__(self, *args, **kwargs): + super(CachedS3BotoStorage, self).__init__(*args, **kwargs) + self.local_storage = get_storage_class( + "compressor.storage.CompressorFileStorage")() + + def save(self, name, content): + name = super(CachedS3BotoStorage, self).save(name, content) + self.local_storage._save(name, content) + return name + +#. Set your :ref:`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/"``). + +.. _CDN: http://en.wikipedia.org/wiki/Content_delivery_network +.. _Amazon S3: https://s3.amazonaws.com/ +.. _boto: http://boto.cloudhackers.com/ +.. _django-storages: http://code.welldev.org/django-storages/ +.. _django-staticfiles: http://github.com/jezdez/django-staticfiles/ +.. _STATIC_ROOT: http://docs.djangoproject.com/en/dev/ref/settings/#static-root +.. _STATIC_URL: http://docs.djangoproject.com/en/dev/ref/settings/#static-url +.. _STATICFILES_STORAGE: http://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/#staticfiles-storage diff --git a/docs/settings.txt b/docs/settings.txt new file mode 100644 index 000000000..37da2e646 --- /dev/null +++ b/docs/settings.txt @@ -0,0 +1,284 @@ +.. _settings: + +Settings +-------- + +Django Compressor has a number of settings that control its behavior. +They've been given sensible defaults. + +.. _compress: + +COMPRESS +^^^^^^^^ + +:Default: the opposite of ``DEBUG`` + +Boolean that decides if compression will happen. + +.. _compress_url: + +COMPRESS_URL +^^^^^^^^^^^^ + +:Default: ``STATIC_URL`` (``MEDIA_URL`` for older Django versions) + +Controls the URL that linked files will be read from and compressed files +will be written to. + +.. note:: + + This setting defaults to ``MEDIA_URL`` in case ``STATIC_URL`` + is not given or empty, e.g. on older Django versions (<1.3). + +.. _compress_root: + +COMPRESS_ROOT +^^^^^^^^^^^^^ + +:Default: ``STATIC_ROOT`` (``MEDIA_ROOT`` for older Django versions) + +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``. + +.. note:: + + This setting defaults to ``MEDIA_ROOT`` in case ``STATIC_ROOT`` + is not given, e.g. on older Django versions (<1.3). + +COMPRESS_OUTPUT_DIR +^^^^^^^^^^^^^^^^^^^ + +:Default: ``'CACHE'`` + +Controls the directory inside COMPRESS_ROOT_ that compressed files will +be written to. + +COMPRESS_CSS_FILTERS +^^^^^^^^^^^^^^^^^^^^ + +:Default: ``['compressor.filters.css_default.CssAbsoluteFilter']`` + +A list of filters that will be applied to CSS. + +COMPRESS_JS_FILTERS +^^^^^^^^^^^^^^^^^^^ + +:Default: ``['compressor.filters.jsmin.JSMinFilter']`` + +A list of filters that will be applied to javascript. + +.. _compress_precompilers: + +COMPRESS_PRECOMPILERS +^^^^^^^^^^^^^^^^^^^^^ + +:Default: ``()`` + +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: + +#. mimetype + The mimetype of the file or inline code should that should be compiled. + +#. 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. + +Example:: + + 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}'), + ) + +With that setting (and CoffeeScript_ installed), you could add the following +code to your templates: + +.. code-block:: django + + {% load compress %} + + {% compress js %} + + {% endcompress %} + +This would give you something like this:: + + + +The same works for less_, too: + +.. code-block:: django + + {% load compress %} + + {% compress css %} + + + {% endcompress %} + +Which would be rendered something like:: + + + +.. _less: http://lesscss.org/ +.. _CoffeeScript: http://jashkenas.github.com/coffee-script/ + +.. _compress_storage: + +COMPRESS_STORAGE +^^^^^^^^^^^^^^^^ + +:Default: ``'compressor.storage.CompressorFileStorage'`` + +The dotted path to a Django Storage backend to be used to save the +compressed files. + +Django Compressor ships with one additional storage backend: + +* ``'compressor.storage.GzipCompressorFileStorage'`` + + A subclass of the default storage backend, which will additionally + create ``*.gz`` files of each of the compressed files. + +.. _compress_parser: + +COMPRESS_PARSER +^^^^^^^^^^^^^^^ + +:Default: ``'compressor.parser.BeautifulSoupParser'`` + +The backend to use when parsing the JavaScript or Stylesheet files. +The backends included in Django Compressor: + +- ``compressor.parser.BeautifulSoupParser`` +- ``compressor.parser.LxmlParser`` + +See :ref:`dependencies` for more info about the packages you need +for each parser. + +.. _compress_cache_backend: + +COMPRESS_CACHE_BACKEND +^^^^^^^^^^^^^^^^^^^^^^ + +:Default: ``"default"`` or ``CACHE_BACKEND`` + +The backend to use for caching, in case you want to use a different cache +backend for Django Compressor. + +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. + +If you have not set ``CACHES`` and are using the old ``CACHE_BACKEND`` +setting, ``COMPRESS_CACHE_BACKEND`` defaults to the ``CACHE_BACKEND`` setting. + +COMPRESS_REBUILD_TIMEOUT +^^^^^^^^^^^^^^^^^^^^^^^^ + +:Default: ``2592000`` (30 days in seconds) + +The period of time after which the compressed files are rebuilt even if +no file changes are detected. + +COMPRESS_MINT_DELAY +^^^^^^^^^^^^^^^^^^^ + +:Default: ``30`` (seconds) + +The upper bound on how long any compression should take to run. Prevents +dog piling, should be a lot smaller than COMPRESS_REBUILD_TIMEOUT_. + +COMPRESS_MTIME_DELAY +^^^^^^^^^^^^^^^^^^^^ + +:Default: ``10`` + +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_. + +COMPRESS_OFFLINE +^^^^^^^^^^^^^^^^ + +:Default: ``False`` + +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. + +To compress the files "offline" and update the offline cache you have +to use the ``compress`` management command, e.g. during deployment. +In case you don't use the ``compress`` management command, Django +Compressor will automatically fallback to the automatic compression. + +It'll will look in the templates that can be found with the template +loader you specify in ``TEMPLATE_LOADERS`` for ``{% compress %}`` blocks +and use 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_. + +The result of running the ``compress`` management command will be saved +in the cache as defined in COMPRESS_CACHE_BACKEND_ for the number of +seconds defined in COMPRESS_OFFLINE_TIMEOUT_. + +COMPRESS_OFFLINE_TIMEOUT +^^^^^^^^^^^^^^^^^^^^^^^^ + +: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. + +COMPRESS_OFFLINE_CONTEXT +^^^^^^^^^^^^^^^^^^^^^^^^ + +: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. It's similar to a template context and should be used if a +variable is used in the blocks, e.g.: + +.. code-block:: django + + {% load compress %} + {% compress js %} + + {% endcompress %} + +Since this template requires a variable (``path_to_files``) you need to +specify this in your settings before using the ``compress`` management +command:: + + COMPRESS_OFFLINE_CONTEXT = { + 'path_to_files': '/static/js/', + } + +If not specified the COMPRESS_OFFLINE_CONTEXT will fall back to contain +the commonly used setting to refer to saved files ``MEDIA_URL``. + +For forward compatibility Django Compressor will also add the ``STATIC_URL`` +setting (added in Django 1.3) to the COMPRESS_OFFLINE_CONTEXT_ if it's +available. diff --git a/docs/usage.txt b/docs/usage.txt new file mode 100644 index 000000000..8f0a4eb38 --- /dev/null +++ b/docs/usage.txt @@ -0,0 +1,87 @@ +Usage +===== + +.. code-block:: django + + {% load compress %} + {% compress %} + + {% endcompress %} + +Examples +-------- + +.. code-block:: django + + {% load compress %} + + {% compress css %} + + + + {% endcompress %} + +Which would be rendered something like: + +.. code-block:: django + + + +or: + +.. code-block:: django + + {% load compress %} + + {% compress js %} + + + {% endcompress %} + +Which would be rendered something like: + +.. code-block:: django + + + +Linked files must be accesible via :ref:`COMPRESS_URL `. +If DEBUG is ``True``, off-site files will throw exceptions. If DEBUG is +``False`` they will be silently stripped. + +If the :ref:`COMPRESS ` setting is ``False`` (defaults to the +opposite of DEBUG) the ``compress`` template tag simply returns exactly +what it was given, to ease development. + +.. warning:: + + 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 + Django's `caching documentation`_). + +.. _memcached: http://memcached.org/ +.. _caching documentation: http://docs.djangoproject.com/en/1.2/topics/cache/#memcached + +CSS Notes +--------- + +All relative ``url()`` bits specified in linked CSS files are automatically +converted to absolute URLs while being processed. Any local absolute URLs (those +starting with a ``'/'``) are left alone. + +Stylesheets that are ``@import``'d are not compressed into the main file. +They are left alone. + +If the media attribute is set on