more structured quick start

.gitignore

@@ -1,3 +1,4 @@
+*~
 *.pyc
 
 Django_Select2.egg-info

django_select2/forms.py

@@ -20,26 +20,27 @@
     drop-in-replacement for Django's default
     select widgets.
 
-    2. **Heavy** --
+    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.
 
-    3. **Model** --
+    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.
 
-Heavy widgets have the word 'Heavy' in their name.
-Light widgets are normally named, i.e. there is no
-'Light' word in their names.
+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
+in their names.
 
 .. inheritance-diagram:: django_select2.forms
     :parts: 1

docs/developers.rst

@@ -0,0 +1,15 @@
+Hints to Developers
+=========================
+
+Documentation pull requests welcome.
+
+Please do not add the "missing" Makefile.  That is intentionally so.
+Compile the docs locally by ways of ``python setup.py build_sphinx``.
+
+Bug reports welcome, even more so if they include a correct patch.  Much
+more so if you start your patch by adding a failing unit test, and correct
+the code until zero unit tests fail.
+
+Please note: the test suite uses the newly introduced f-strings, so that it
+needs Python3.6+ to run.  The code itself is targeted at Python3.5+.
+

docs/django_select2.rst

@@ -49,8 +49,9 @@ DjangoSelect2 handles the initialization of select2 fields automatically. Just i
 ``{{ form.media.js }}`` in your template before the closing ``body`` tag. That's it!
 
 If you insert forms after page load or if you want to handle the initialization
-yourself, DjangoSelect2 provides a jQuery plugin. It will handle both normal and
-heavy fields. Simply call ``djangoSelect2(options)`` on your select fields.::
+yourself, DjangoSelect2 provides a jQuery plugin, replacing and enhancing the Select2
+plugin.  It will handle both normal and heavy fields. Simply call
+``djangoSelect2(options)`` on your select fields.::
 
         $('.django-select2').djangoSelect2();
 
@@ -59,6 +60,9 @@ You can pass see `Select2 options <https://select2.github.io/options.html>`_ if
 
         $('.django-select2').djangoSelect2({placeholder: 'Select an option'});
 
+Please replace all your ``.select2`` invocations with the here provided
+``.djangoSelect2``.
+
 Security & Authentication
 -------------------------
 

docs/get_started.rst

@@ -8,6 +8,17 @@ Overview
 .. automodule:: django_select2
     :members:
 
+Assumptions
+-----------
+
+* You have a Django project, possibly with models linked by foreign key fields,
+* are using Python3,
+* set up a virtual environment with ``python3 -m venv <location>``,
+* activated the virtual environment,
+* installed ``django`` using ``pip``,
+* are already using Django forms,
+* and your select lists are too long, or they look ugly to you.
+
 Installation
 ------------
 
@@ -17,11 +28,12 @@ Installation
 
 2. Add ``django_select2`` to your ``INSTALLED_APPS`` in your project settings.
 
+3. Add ``django_select`` to your ``urlconf``::
 
-3. Add ``django_select`` to your ``urlconf`` **if** you use any
-:class:`ModelWidgets <.django_select2.forms.ModelSelect2Mixin>`::
+        path('select2/', include('django_select2.urls')),
 
-        url(r'^select2/', include('django_select2.urls')),
+   You can safely skip this one if you do not use any
+   :class:`ModelWidgets <.django_select2.forms.ModelSelect2Mixin>`
 
 Quick Start
 -----------
@@ -30,19 +42,22 @@ Here is a quick example to get you started:
 
 0. Follow the installation instructions above.
 
-1. Add a select2 widget to the form. For example if you wanted Select2 with multi-select you would use
-``Select2MultipleWidget``
-Replacing::
+1. Replace native Django forms widgets with one of the several ``django_select2.form`` widgets.
+   Start by importing them into your forms.py, right next to django own ones::
 
-        class MyForm(forms.Form):
-            things = ModelMultipleChoiceField(queryset=Thing.objects.all())
+     from django import forms
+     from django_select2 import forms as s2forms
 
-with::
+   Then let's assume you have a model with a Choice, a ForeignKey, and a
+   ManyToMany field, you would add this information to your Form Meta
+   class::
 
-        from django_select2.forms import Select2MultipleWidget
-
-        class MyForm(forms.Form):
-            things = ModelMultipleChoiceField(queryset=Thing.objects.all(), widget=Select2MultipleWidget)
+        widgets = {
+            'category': s2forms.Select2Widget,
+            'author': s2forms.ModelSelect2Widget(model=auth.get_user_model(),
+                                                 search_fields=['first_name__istartswith', 'last_name__icontains']),
+            'attending': s2forms.ModelSelect2MultipleWidget …
+        }
 
 2. Add the CSS to the ``head`` of your Django template::
 

docs/index.rst

@@ -15,6 +15,7 @@ Contents:
    get_started
    django_select2
    extra
+   developers
 
 Indices and tables
 ==================