Added documentation

django_select2/__init__.py

@@ -7,75 +7,6 @@
 .. _Django: https://www.djangoproject.com/
 .. _Select2: http://ivaynberg.github.com/select2/
 
-Widgets
--------
-
-These components are responsible for rendering
-the necessary JavaScript and HTML markups. Since this whole
-package is to render choices using Select2 JavaScript
-library, hence these components are meant to be used
-with choice fields.
-
-Widgets are generally of two types :-
-
-    1. **Light** --
-    They are not meant to be used when there
-    are too many options, say, in thousands.
-    This is because all those options would
-    have to be pre-rendered onto the page
-    and JavaScript would be used to search
-    through them. Said that, they are also one
-    the most easiest to use. They are almost
-    drop-in-replacement for Django's default
-    select widgets.
-
-    2. **Heavy** --
-    They are suited for scenarios when the number of options
-    are large and need complex queries (from maybe different
-    sources) to get the options.
-    This dynamic fetching of options undoubtedly requires
-    Ajax communication with the server. Django-Select2 includes
-    a helper JS file which is included automatically,
-    so you need not worry about writing any Ajax related JS code.
-    Although on the server side you do need to create a view
-    specifically to respond to the queries.
-
-    Heavies have further specialized versions called -- **Auto Heavy**.
-    These do not require views to serve Ajax requests.
-    When they are instantiated, they register themselves
-    with one central view which handles Ajax requests for them.
-
-Heavy widgets have the word 'Heavy' in their name.
-Light widgets are normally named, i.e. there is no
-'Light' word in their names.
-
-**Available widgets:**
-
-:py:class:`.Select2Widget`,
-:py:class:`.Select2MultipleWidget`,
-:py:class:`.HeavySelect2Widget`,
-:py:class:`.HeavySelect2MultipleWidget`,
-:py:class:`.ModelSelect2Widget`,
-:py:class:`.ModelSelect2MultipleWidget`,
-:py:class:`.HeavySelect2TagWidget`,
-:py:class:`.GenreSelect2TagWidget`
-
-`Read more`_
-
-Views
------
-
-The view - `Select2View`, exposed here is meant
-to be used with 'Heavy' fields and widgets.
-
-**Imported:**
-
-:py:class:`.Select2View`, :py:data:`.NO_ERR_RESP`
-
-`Read more`_
-
-.. _Read more: http://blog.applegrew.com/2012/08/django-select2/
-
 """
 
 __version__ = "5.0.0"

django_select2/conf.py

@@ -1,15 +1,53 @@
 # -*- coding: utf-8 -*-
+"""Settings for Django-Select2."""
 from __future__ import absolute_import, unicode_literals
 
 from appconf import AppConf
 from django.conf import settings  # NOQA
 
-__all__ = ('settings',)
+__all__ = ('settings', 'Select2Conf')
 
 
 class Select2Conf(AppConf):
+
+    """Settings for Django-Select2."""
+
     CACHE_BACKEND = 'default'
+    """
+    Django-Select2 uses Django's cache to sure a consistent state across multiple machines.
+
+    Example of settings.py::
+
+        CACHES = {
+            "default": {
+                "BACKEND": "django_redis.cache.RedisCache",
+                "LOCATION": "redis://127.0.0.1:6379/1",
+                "OPTIONS": {
+                    "CLIENT_CLASS": "django_redis.client.DefaultClient",
+                }
+            },
+            'select2': {
+                'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
+                'LOCATION': '127.0.0.1:11211',
+            }
+        }
+
+        # Set the cache backend to select2
+        SELECT2_CACHE_BACKEND = 'select2'
+
+    .. tip:: To ensure a consistent state across all you machines you need to user
+        a consistent external cache backend like Memcached, Redis or a database.
+
+    .. note:: The timeout of select2's caching backend determines
+        how long a browser session can last.
+        Once widget is dropped from the cache the json response view will return a 404.
+    """
     CACHE_PREFIX = 'select2_'
+    """
+    If you caching backend doesn't support multiple databases
+    you can isolate select2 using the cache prefix setting.
+    It has set `select2_` as a default value, which you can change if needed.
+    """
 
     class Meta:
         prefix = 'SELECT2'