update and improve documentation

docs/customization.rst

@@ -4,21 +4,31 @@
 Customization
 =============
 
-.. note::
-
-  Describes how to customize and add your own functionality to django-compress
-
-
-django-compress can be customized an a couple of ways.
+``django-compress`` can be customized an a couple of ways.
 
 If you need to change the output of the HTML-tags generated from the templatetags,
 this can be done by overriding the templates ``compress/css.html`` and ``compress/js.html``.
 
 You can also write your own compressor-class, if you for example want to implement
 other types of compressors.
-All you need to do is to define a compress_css and/or a compress_js functions in a
-class that inherits from ``compress.compressors.CompressorBase``,
-and specify it in the tuple of filters (``COMPRESS_CSS_COMPRESSORS``/``COMPRESS_JS_COMPRESSORS``)
-(see :doc:`configuration` for more information) in the settings.
 
-For now, see the files under `compressors/` for more details.
\ No newline at end of file
+All you need to do is to create a class that inherits from ``compress.compressors.CompressorBase``
+and implements ``compress_css`` and/or a ``compress_js`` when needed.
+
+Finally, specify it in the tuple of compressors ``COMPRESS_CSS_COMPRESSORS`` or 
+``COMPRESS_JS_COMPRESSORS`` (see :doc:`configuration` for more information) in the settings.
+
+Example
+=======
+
+A custom compressor for a imaginary compressor called jam ::
+
+  from compress.compressors import CompressorBase
+  
+  class JamCompressor(CompressorBase):
+    def compress_js(self, js):
+      return jam.compress(js)
+    
+    def compress(self, css):
+      return jam.compress(css)
+  

docs/farfuturexpires.rst → docs/farfutureexpires.rst

-.. _ref-farfuturexpires:
+.. _ref-farfutureexpires:
 
 ==================
-Far Future Expires
+Far future expires
 ==================
 
-Details about the "Far Future Expires" technique, and how to implement it with help from django-compress
+Details about the "Far future expires" technique, and how to implement it with help from django-compress
 
-General details and considerations about the "Far Future Expires" technique
+General details and considerations about the "Far future expires" technique
 ===========================================================================
 
 If you really want to make sure that your CSS and JavaScript files get cached by
@@ -15,14 +15,14 @@ This means that you send the Expires HTTP-header with a date that is far in the
 resulting in the file being cached at the client (almost) forever
 
 If you do not specify an Expires header, the files will be requested again,
-and the server will respond "304 Not Modified" - which means that the file that
+and the server will respond "*304 Not Modified*" - which means that the file that
 the client got in its cache is still up-to-date. *However, a HTTP request will still be made anyway.*
 The actual data does not get sent, but there will still be unnecessary HTTP requests, which can be avoided.
 
-Most modern browser implement "Heuristic expiration", so it will actually not be
-"304 Not Modified" for your static files on every request, however, the
+Most modern browser implement "*Heuristic expiration*", so it will actually not be
+"*304 Not Modified*" for your static files on every request, however, the
 `HTTP specification does not specify <http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html>`_ (see section 13.2.2)
-how "Heuristic expiration" should be handled by the browsers.
+how "*Heuristic expiration*" should be handled by the browsers.
 Therefore it is recommended to explicitly set the Expires header, to make sure all
 browsers cache the files in the preferred way.
 
@@ -30,16 +30,18 @@ This technique obviously has a drawback, when you want to change your files,
 you need to change their names, since their URLs will be cached... that's right: forever!
 The solution to that is pretty obvious too: change the URLs.
 
-django-compress with COMPRESS_VERSION 
-=====================================
+COMPRESS_VERSION 
+================
 
 If you specify ``COMPRESS_VERSION`` in your configuration, you can add a placeholder
 to the filenames to output the version number of the different files.
-See :doc:`configuration` for more information.
+
 The filename itself will be changed when any of the source files are updated.
 
-Configuration of web server (that serves MEDIA_URL)
-===================================================
+See :doc:`configuration` for more information.
+
+Configuration of web server
+===========================
 
 Apache
 ------
@@ -57,12 +59,11 @@ For example ::
         ExpiresDefault "access plus 10 years"
     </Directory>
 
-Apache also allows the specify files by their mime-type:
-<pre><code>
-ExpiresActive On
-ExpiresByType text/css "access plus 10 years"
-ExpiresByType application/x-javascript "access plus 10 years"
-</code></pre>
+Apache also allows the specify files by their mime-type ::
+
+  ExpiresActive On
+  ExpiresByType text/css "access plus 10 years"
+  ExpiresByType application/x-javascript "access plus 10 years"
 
 lighttpd
 --------

docs/features.rst

@@ -10,25 +10,27 @@ It adheres to the DRY principle, you set up your CSS-files and JavaScript-files
 in your project settings, and you are done.
 There is no need to enter the names in your template again (a couple of template tags takes care of that).
 
-* Group/concatenate your CSS/JavaScript source files to single files,
-  and run the code through specified compressors
+* Group and concatenate your stylesheets and jaavscripts source files to single files,
+  and run the code through specified compressors.
 
 * Provides sane defaults for CSS and JavaScript minification (YUI compressor required).
 
-* A compressor for YUI Compressor, Google Closure Compiler, UglifyJS is included.
+* A compressor for **YUI Compressor**, **Google Closure Compiler**, **UglifyJS** is included.
 
 * It’s easy and straightforward to write custom compressors to generate the output.
 
-* A last-modifcation/version part can automatically be appended to the filename
+* A last-modification and/or version part can automatically be appended to the filename
   of the outputted files to make use of “far future Expires HTTP header),
   and provide an automated way of updating the content without delays.
 
 * You setup and group your CSS and JavaScript-files in the settings,
   and set up whetter or not you want your files to be compressed.
 
-* Templatetags to output CSS (<link...>) or JavaScript (<script...>) tags
+* Templatetags to output CSS (``<link>``) or JavaScript (``<script>``) tags
   with the compressed files if ``COMPRESS = True``, or otherwise the source files.
 
 * The compressed files will be updated (if needed) when you are accessing them
-  from the templatetags. This only applies when ``COMPRESS_AUTO`` is enabled.
+  from the templatetags.
+  
+  This only applies when ``COMPRESS_AUTO`` is enabled.
   You can manually update them with ``./manage.py synccompress``.

docs/index.rst

@@ -49,7 +49,7 @@ Table Of Contents
    configuration
    versioning
    customization
-   farfuturexpires
+   farfutureexpires
    backwardsincompatiblechanges
 
 Indices and tables

docs/installation.rst

@@ -5,9 +5,21 @@ Installation
 ============
 
 Installation is pretty straight-forward and follows the same installation
-procedure as many other Django applications.
-django-compress does not create any models, so you do not need to configure a database.
+procedure as many other *Django* applications.
 
+``django-compress`` does not create any models, so you do not need to configure a database.
+
+Install instructions
+====================
+
+1. Either check out django-compress from GitHub_ or to pull a release off PyPI_.
+   Doing ``pip install django-compress`` or ``easy_install django-compress`` is all that should be required.
+
+2. Add 'compress' to your ``INSTALLED_APPS``
+
+
+.. _GitHub: http://github.com/pelme/django-compress
+.. _PyPI: http://pypi.python.org/
 
 Recommendations
 ===============
@@ -17,13 +29,3 @@ YUI Compressor is an excellent stand-alone application for dealing with JS and C
 YUI Compressor can be downloaded from: http://developer.yahoo.com/yui/compressor/.
 
 If you do not install YUI COMPRESSOR, make sure to disable the compressor in your settings.
-
-Install instructions
-====================
-
-1. Either check out django-compress from GitHub_ or to pull a release off PyPI_.
-  Doing ``pip install django-compress`` or ``easy_install django-compress`` is all that should be required.
-2. Add 'compress' to your INSTALLED_APPS 
-
-.. _GitHub: http://github.com/pelme/django-compress
-.. _PyPI: http://pypi.python.org/

docs/usage.rst

@@ -21,13 +21,13 @@ Management command
 You can update and force updates of the compressed file(s) with the management command “synccompress”.
 This makes it possible to keep the files updated manually.
 
-The command is ::
+The command is (assuming you are in you project-folder that contains ``manage.py``). ::
 
-    manage.py synccompress
+    ./manage.py synccompress
 
-
-(assuming you are in you project-folder that contains ``manage.py``).
-To force all files to be re-generated, use the argument ``--force`` (e.g. ``./manage.py synccompress --force``)
+To force all files to be re-generated, use the argument ``--force`` :: 
+  
+    ./manage.py synccompress --force
 
 Templatetags
 ============
@@ -44,7 +44,7 @@ depending on the ``COMPRESS`` setting, if you do not specify the ``COMPRESS`` se
 the source files will be used in DEBUG-mode, and compressed files in non-DEBUG-mode.
 
 Example
-=======
+-------
 
 If you have specified the CSS-groups “screen” and “print” and a JavaScript-group
 with the name “scripts”, you would use the following code to output them all ::
@@ -53,8 +53,3 @@ with the name “scripts”, you would use the following code to output them all
    {% compressed_css 'screen' %}
    {% compressed_css 'print' %}
    {% compressed_js 'scripts' %}
-
-Far future Expires
-==================
-
-Far future Expires can be used with the bump_filename-option, see the :doc:`farfuturexpires` page for more information. 

docs/versioning.rst

@@ -7,33 +7,33 @@ Versioning
 There are several ways for generating version strings. Basically, two types are available.
 These are: mtime version strings and hash version strings.
 
-mtime version strings (default)
-===============================
+Modification time version
+=========================
 
 This is the default method for generating version strings. In short, when invoked, it checks whether any of the source files system timestamps (mtime) is newer than the version string of the corresponding compressed file. If that is the case, the compressed output file version string will be the mtime of the most recent source file.
 
-hash version strings
-====================
+Hash version
+============
 
 Hash-based versioning works by generating a hash string based on the contents of the source files. Available hash-based versioning methods are MD5 and SHA-1.
 
-MD5 version strings
--------------------
+MD5 version
+-----------
 
 To generate MD5 version strings, put this in your `settings.py` ::
 
     COMPRESS_VERSIONING = 'compress.versioning.hash.MD5Versioning'
 
-SHA-1 version string
---------------------
+SHA-1 version
+-------------
 
 To generate SHA-1 version strings, put this in your `settings.py`::
 
     COMPRESS_VERSIONING = 'compress.versioning.hash.SHA1Versioning'
 
 
-Git version strings
-===================
+Git version
+===========
 
 Versions formed on git revisions in codebase. Provides a fast way to check if any of your files changed that
 will be consistent across multiple web servers so that they all generate the same version numbers for each
@@ -43,15 +43,15 @@ Assumes deployment is git repositiory. Requires GitPython 0.2.0.
 GitPython 0.3.0 uses an async library that does not currently play well with Django. To install using Git just do
 pip install GitPython==0.2.0-beta1.
 
-Git revision version strings
-----------------------------
+Git revision version
+--------------------
 
 To generate versions based on revision of every file in your source file list, put this in your `settings.py`::
 
     COMPRESS_VERSIONING = 'compress.versioning.git.GitVersioningBase'
 
-Git HEAD last revision version strings
---------------------------------------
+Git HEAD last revision version
+------------------------------
 
 To generate versions based on the latest revision of HEAD in your git repository (which assumes all of your source files are in the
 same repository), put this in your `settings.py`::