Merge pull request #770 from karyon/clarify_offline_compression

Clarify offline compression

docs/behind-the-scenes.txt

@@ -1,6 +1,6 @@
 .. _behind_the_scenes:
 
-Behind the scenes
+Behind the Scenes
 =================
 
 This document assumes you already have an up and running instance of
@@ -8,25 +8,25 @@ 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.
 
-Offline cache
+Offline compression
 -------------
 
-If offline cache is activated, the first thing {% compress %} tries to do is
+If offline compression is activated, the {% compress %} tag will try to
 retrieve the compressed version for its nodelist from the offline manifest
 cache. 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 offline cache manifest is just a json file, stored on disk inside the
 directory that holds the compressed files. The format of the manifest is simply
-a key <=> value dictionary, with the hash of the nodelist being the key,
+a key-value dictionary, with the hash of the nodelist being the key,
 and the HTML containing the element code for the combined file or piece of code
-being the value. Generating the offline manifest, using the ``compress``
-management command, also generates the combined files referenced in the manifest.
+being the value. The ``compress`` management command generates the
+offline manifest as well as the combined files referenced in the manifest.
 
-If offline cache is activated and the nodelist hash can not be found inside the
+If offline compression is enabled and the nodelist hash can not be found inside the
 manifest, {% compress %} will raise an ``OfflineGenerationError``.
 
-If offline cache is de-activated, the following happens:
+If offline compression is disabled, the following happens:
 
 First step: parsing and file list
 ---------------------------------

docs/jinja2.txt

@@ -1,10 +1,11 @@
-Jinja2 In-Request Support
-=========================
+Jinja2 Support
+==============
 
 Django Compressor comes with support for Jinja2_ via an extension.
 
-Plain Jinja2
-------------
+
+In-Request Compression
+----------------------
 
 In order to use Django Compressor's Jinja2 extension we would need to pass
 ``compressor.contrib.jinja2ext.CompressorExtension`` into environment::
@@ -25,20 +26,21 @@ From now on, you can use same code you'd normally use within Django templates::
     template.render({'STATIC_URL': settings.STATIC_URL})
 
 
-Jinja2 Offline Compression Support
-==================================
-You'd need to configure ``COMPRESS_JINJA2_GET_ENVIRONMENT`` so that
+Offline Compression
+-------------------
+
+Usage
+^^^^^
+First, you will need to configure ``COMPRESS_JINJA2_GET_ENVIRONMENT`` so that
 Compressor can retrieve the Jinja2 environment for rendering.
 This can be a lambda or function that returns a Jinja2 environment.
 
-Usage
------
-Run the following compress command along with an ``--engine`` parameter. The
-parameter can be either jinja2 or django (default). For example,
+Then, run the following compress command along with an ``--engine`` parameter.
+The parameter can be either jinja2 or django (default). For example,
 ``./manage.py compress --engine jinja2``.
 
 Using both Django and Jinja2 templates
---------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 There may be a chance that the Jinja2 parser is used to parse Django templates
 if you have a mixture of Django and Jinja2 templates in the same location(s).
 This should not be a problem since the Jinja2 parser will likely raise a
@@ -56,7 +58,7 @@ However, it is still recommended that you do not mix Django and Jinja2
 templates in the same project.
 
 Limitations
------------
+^^^^^^^^^^^
 - Does not support ``{% import %}`` and similar blocks within
   ``{% compress %}``  blocks.
 - Does not support ``{{super()}}``.
@@ -65,7 +67,7 @@ Limitations
   should run fine.
 
 Jinja2 templates location
--------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^
 IMPORTANT: For Compressor to discover the templates for offline compression,
 there must be a template loader that implements the ``get_template_sources``
 method, and is in the ``TEMPLATE_LOADERS`` setting.
@@ -86,7 +88,7 @@ the filesystem loader (``django.template.loaders.filesystem.Loader``) in the
 ``TEMPLATE_DIRS`` setting.
 
 Using your custom loader
-------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 You should configure ``TEMPLATE_LOADERS`` as such::
 
     TEMPLATE_LOADERS = (

docs/remote-storages.txt

@@ -1,6 +1,6 @@
 .. _remote_storages:
 
-Remote storages
+Remote Storages
 ---------------
 
 In some cases it's useful to use a CDN_ for serving static files such as

docs/scenarios.txt

@@ -47,6 +47,8 @@ You will find offline compression beneficial if:
 
 * You store compressed files on a CDN.
 
+* You want the best possible performance.
+
 Caveats
 -------
 

docs/settings.txt

@@ -459,9 +459,7 @@ Offline settings
     :Default: ``False``
 
     Boolean that decides if compression should be done outside of the
-    request/response loop. (See :ref:`behind_the_Scenes` for more.) This allows
-    to pre-compress CSS and JavaScript files and works just like the automatic
-    compression with the ``{% compress %}`` tag.
+    request/response loop. See :ref:`offline_compression` for details.
 
 .. attribute:: COMPRESS_OFFLINE_TIMEOUT
 

docs/usage.txt

@@ -107,22 +107,22 @@ access it in the `post_compress signal <signals>`.
 .. _memcached: http://memcached.org/
 .. _caching documentation: https://docs.djangoproject.com/en/1.8/topics/cache/#memcached
 
-.. _pre-compression:
 
-Pre-compression
+.. _offline_compression:
+
+Offline Compression
 ---------------
 
-Django Compressor comes with an optional ``compress`` management command to
-run the compression 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.
+Django Compressor has the ability to run the compression "offline",
+i.e. outside of the request/response loop -- independent from user requests.
+If offline compression is enabled, no new files are generated during a request
+and the ``{% compress %}`` tag simply inserts links to the files in the
+offline cache (see :ref:`behind_the_scenes` for details). This results in better
+performance and enables certain deployment scenarios (see :ref:`scenarios`).
 
-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 :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.
+To use offline compression, enable the :attr:`django.conf.settings.COMPRESS_OFFLINE`
+setting and then run the ``compress`` management command to compress your assets
+and update the offline cache.
 
 The command parses all templates that can be found with the template
 loader (as specified in the TEMPLATE_LOADERS_ setting) and looks for
@@ -137,20 +137,18 @@ in the blocks, e.g.:
 
     {% load compress %}
     {% compress js %}
-    <script src="{{ path_to_files }}js/one.js" type="text/javascript" charset="utf-8"></script>
+    <script type="text/javascript">
+        alert("{{ greeting }}");
+    </script>
     {% endcompress %}
 
-Since this template requires a variable (``path_to_files``) you need to
-specify this in your settings before using the ``compress`` management
-command::
+Since this template requires a variable (``greeting``) you need to specify
+this in your settings before using the ``compress`` management command::
 
     COMPRESS_OFFLINE_CONTEXT = {
-        'path_to_files': '/static/js/',
+        'greeting': 'Hello there!',
     }
 
-If not specified, the ``COMPRESS_OFFLINE_CONTEXT`` will by default contain
-the commonly used setting to refer to saved files ``STATIC_URL``.
-
 The result of running the ``compress`` management command will be cached
 in a file called ``manifest.json`` using the :attr:`configured storage
 <django.conf.settings.COMPRESS_STORAGE>` to be able to be transferred from your development