Improve documentation.

docs/advanced.rst

@@ -0,0 +1,61 @@
+Advanced topics
+===============
+
+Nginx configuration
+-------------------
+
+To improve the performance of static file delivery, you might use the cache options
+Nginx provide.
+
+Here is an example configuration of Nginx together with uwsgi:
+
+.. code-block:: nginx
+
+    # Prepare a cache with 100 MB storage capacity
+    uwsgi_cache_path
+        /path/to/cache
+        levels=1:2
+        keys_zone=static_cache:2m
+        max_size=100m
+        inactive=1w
+        use_temp_path=off;
+
+    # You django backend / uwsgi process
+    upstream app {
+        server django:8000;
+    }
+
+    server {
+        listen 80 default_server;
+        root /var/www;
+
+        location / {
+            try_files $uri @proxy_to_app;
+        }
+
+        # Important section, tell nginx to use the cache for all requests to /static/*
+        location /static/ {
+            uwsgi_cache static_cache;
+            uwsgi_cache_use_stale updating;
+            uwsgi_cache_lock on;
+            uwsgi_cache_valid any 1w;
+            uwsgi_cache_key $host$request_uri;
+
+            include uwsgi_params;
+            uwsgi_pass app;
+        }
+
+        location @proxy_to_app {
+            include uwsgi_params;
+            uwsgi_pass app;
+        }
+    }
+
+
+Please note, this is just an example. Please test the configration before putting this
+to production.
+
+.. note::
+
+    You are not bound to use uWSGI. Gunicorn will work fine too - you just need to
+    find the Nginx equivalents to the uwsgi_* settings (most of them will be prefixed proxy_*)

docs/index.rst

@@ -9,7 +9,7 @@ All Contents
     :glob:
 
     installation
-    usage
+    advanced
     api
     changelog
 

docs/installation.rst

@@ -15,6 +15,28 @@ In addition, you have to add ``'static_delivery.StaticDeliveryMiddleware'``
 to the ``MIDDLEWARE`` setting in your ``settings.py``. Make sure to add the middleware
 to the top of the list.
 
-Thats it, now continue to the :doc:`Usage section <usage>` to learn how to optimize
-your reverse proxy for a good performance - serving static files via Django is never
-a fast way.
+.. code-block:: python
+
+    MIDDLEWARE = [
+        'static_delivery.StaticDeliveryMiddleware',
+        # ... all other middlewares
+    ]
+
+Please make sure that your ``staticfiles`` related settings are configured properly.
+Besides having ``STATIC_ROOT`` and ``STATIC_URL`` set, you have to use a staticfile
+storage with hashed file names, for example ``ManifestStaticFilesStorage``.
+
+.. code-block:: python
+
+    # Filesystem path there collected staticfiles are stored
+    STATIC_ROOT = '/var/www/static'
+
+    # Public base path to access files in STATIC_ROOT
+    STATIC_URL = '/static/'
+
+    STATICFILES_STORAGE = 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'
+
+
+Thats it, now continue to the :doc:`Advanced topics section <advanced>` to learn
+how to optimize your reverse proxy for a good performance - serving static files
+via Django is never a fast way.