Note case in which cache is not needed (#233)

Co-authored-by: Johannes Maron <[email protected]>

Author: vanschelven

django_select2/forms.py

@@ -7,36 +7,43 @@
 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 easiest to use. They are a
-    drop-in-replacement for Django's default
-    select widgets.
-
-    2(a). **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.
-
-    2(b). **Model** --
-    Model-widgets are a further specialized versions of Heavies.
-    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.
+Widgets are generally of tree types:
+Light, Heavy and Model.
+
+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 easiest to use. They are a
+drop-in-replacement for Django's default
+select widgets.
+
+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.
+
+Model
+~~~~~
+
+Model-widgets are a further specialized versions of Heavies.
+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 and Model widgets have respectively the word 'Heavy' and 'Model' in
 their name.  Light widgets are normally named, i.e. there is no 'Light' word

docs/conf.py

@@ -31,6 +31,7 @@
 
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",
     "sphinx.ext.napoleon",
     "sphinx.ext.inheritance_diagram",
     "sphinx.ext.intersphinx",

docs/index.rst

@@ -32,8 +32,9 @@ Add ``django_select`` to your URL root configuration:
     ]
 
 
-``django-select2`` requires a cache backend which is **persistent**
-across all application servers..
+The :ref:`Model` -widgets require a **persistent** cache backend across
+all application servers. This is because the widget needs to store
+meta data to be able to fetch the results based on the user input.
 
 **This means that the** :class:`.DummyCache` **backend will not work!**