Add more comprehencive gettings started app and example

Author: codingjoe

.gitignore

@@ -23,3 +23,4 @@ ghostdriver.log
 
 coverage.xml
 .eggs/
+db.sqlite3

README.rst

@@ -1,69 +1,21 @@
+==============
 Django-Select2
 ==============
 
-|version| |ci| |coverage| |license|
-
 This is a `Django`_ integration of `Select2`_.
 
 The app includes Select2 driven Django Widgets.
 
-.. note::
-    Django's admin comes with builtin support for Select2
-    since version 2.0 via the `autocomplete_fields`_ feature.
-
-Installation
-------------
-
-1. Install ``django_select2``
-
-.. code:: python
-
-    pip install django_select2
-
-2. Add ``django_select2`` to your ``INSTALLED_APPS`` in your project
-   settings.
-
-3. Add ``django_select`` to your urlconf if you use any "Auto" fields.
-
-.. code:: python
-
-    url(http://github.com/%3Cspan%20class=%22pl-sr%22%3E%3Cspan%20class=%22pl-k%22%3Er%3C/span%3E%3Cspan%20class=%22pl-pds%22%3E'%3C/span%3E%3Cspan%20class=%22pl-c1%22%3E^%3C/span%3Eselect2/%3Cspan%20class=%22pl-pds%22%3E'%3C/span%3E%3C/span%3E,%20include(%3Cspan%20class=%22pl-s%22%3E%3Cspan%20class=%22pl-pds%22%3E'%3C/span%3Edjango_select2.urls%3Cspan%20class=%22pl-pds%22%3E'%3C/span%3E%3C/span%3E)),
-
 Documentation
 -------------
 
 Documentation available at https://django-select2.readthedocs.io/.
 
-External Dependencies
----------------------
-
--  jQuery version 2 This is not included in the package since it is
-   expected that in most scenarios this would already be available.
-
-Example Application
--------------------
-
-Please see ``tests/testapp`` application. This application is used to
-manually test the functionalities of this package. This also serves as a
-good example.
-
-Changelog
----------
-
-See `Github releases`_
+.. note::
+    Django's admin comes with builtin support for Select2
+    via the `autocomplete_fields`_ feature.
 
 
 .. _Django: https://www.djangoproject.com/
 .. _Select2: https://select2.org/
 .. _autocomplete_fields: https://docs.djangoproject.com/en/stable/ref/contrib/admin/#django.contrib.admin.ModelAdmin.autocomplete_fields
-.. _CHANGELOG.md: CHANGELOG.md
-.. _Github releases: https://github.com/applegrew/django-select2/releases
-
-.. |version| image:: https://img.shields.io/pypi/v/Django-Select2.svg
-   :target: https://pypi.python.org/pypi/Django-Select2/
-.. |ci| image:: https://travis-ci.org/applegrew/django-select2.svg?branch=master
-   :target: https://travis-ci.org/applegrew/django-select2
-.. |coverage| image:: https://codecov.io/gh/applegrew/django-select2/branch/master/graph/badge.svg
-   :target: https://codecov.io/gh/applegrew/django-select2
-.. |license| image:: https://img.shields.io/badge/license-APL2-blue.svg
-   :target: https://raw.githubusercontent.com/applegrew/django-select2/master/LICENSE.txt

docs/get_started.rst

@@ -1,7 +1,186 @@
-.. Django-Select2 documentation master file, created by
-   sphinx-quickstart on Sat Aug 25 10:23:46 2012.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. include:: ../README.rst
+
+Installation
+------------
+
+Install ``django-select2``
+
+.. code-block:: python
+
+    python3 -m pip install django-select2
+
+Add ``django_select2`` to your ``INSTALLED_APPS`` in your project settings.
+
+Add ``django_select`` to your urlconf if you use any "Auto" fields.
+
+.. code-block:: python
+
+    from django.urls import include, path
+
+    urlpatterns = [
+        # … other patterns
+        path("select2/", include("django_select2.urls")),
+        # … other patterns
+    ]
+
+Finally make sure you have a persistent cache backend setup
+(not the dummy backen), we will use Redis in this example.
+Make sure you have a Redis server up and running::
+
+    # Debian
+    sudo apt-get install redis-server
+    # macOS
+    brew install redis
+    # install Redis python client
+    python3 -m pip install django-redis
+
+Next, add the cache configuration to your ``settings.py`` as follows:
+
+.. code-block:: python
+
+    CACHES = {
+        # … default cache config and others
+        "select2": {
+            "BACKEND": "django_redis.cache.RedisCache",
+            "LOCATION": "redis://127.0.0.1:6379/2",
+            "OPTIONS": {
+                "CLIENT_CLASS": "django_redis.client.DefaultClient",
+            }
+        }
+    }
+
+    # Tell select2 which cache configuration to use:
+    SELECT2_CACHE_BACKEND = "select2"
+
+
+External Dependencies
+---------------------
+
+-  jQuery is not included in the package since it is
+   expected that in most scenarios this would already be available.
+
+
+Quick Start
+-----------
+
+Here is a quick example to get you started:
+
+First make sure you followed the installation instructions above.
+Once everything is setup, let's start with a simple example.
+
+We have the following model:
+
+.. code-block:: python
+
+    # models.py
+    from django.conf import settings
+    from django.db import models
+
+
+    class Book(models.Model):
+        author = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)
+        co_authors = models.ManyToManyField(settings.AUTH_USER_MODEL, related_name='co_authors')
+
+
+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:
+
+.. code-block:: python
+
+    # forms.py
+    from django import forms
+    from django_select2 import forms as s2forms
+
+    from . import models
+
+
+    class AuthorWidget(s2forms.ModelSelect2Widget):
+        search_fields = [
+            "username__icontains",
+            "email__icontains",
+        ]
+
+
+    class CoAuthorWidget(s2forms.ModelSelect2MultipleWidget):
+        search_fields = [
+            "username__icontains",
+            "email__icontains",
+        ]
+
+
+    class BookForm(forms.ModelForm):
+        class Meta:
+            model = models.Book
+            fields = "__all__"
+            widgets = {
+                "author": AuthorWidget,
+                "co_authors": CoAuthorWidget,
+            }
+
+A simple class based view will do, to render your form:
+
+.. code-block:: python
+
+    # views.py
+    from django.views import generic
+
+    from . import forms, models
+
+
+    class BookCreateView(generic.CreateView):
+        model = models.Book
+        form_class = forms.BookForm
+
+Make sure to add the view to your ``urls.py``:
+
+.. code-block:: python
+
+    # urls.py
+    from django.urls import include, path
+
+    from . import views
+
+    urlpatterns = [
+        # … other patterns
+        path("select2/", include("django_select2.urls")),
+        # … other patterns
+        path("book/create", views.BookCreateView.as_view(), name="book-create"),
+    ]
+
+
+Finally, we need a little template, ``myapp/templates/myapp/book_form.html``
+
+.. code-block:: HTML
+
+    <!DOCTYPE html>
+    <html lang="en">
+    <head>
+        <title>Create Book</title>
+        {{ form.media.css }}
+        <style>
+            input, select {width: 100%}
+        </style>
+    </head>
+    <body>
+        <h1>Create a new Book</h1>
+        <form action="POST">
+            {{ form.as_p }}
+            <input type="submit">
+        </form>
+        <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
+        {{ form.media.js }}
+    </body>
+    </html>
+
+Done - enjoy the wonders of Select2!
+
+
+Changelog
+---------
+
+See `Github releases`_.
+
+.. _Github releases: https://github.com/applegrew/django-select2/releases
 
 All Contents
 ============
@@ -12,7 +191,6 @@ Contents:
    :maxdepth: 2
    :glob:
 
-   get_started
    django_select2
    extra
    CONTRIBUTING

docs/index.rst

@@ -0,0 +1,14 @@
+# Sample App
+
+To run the sample app, please run:
+
+```
+git clone https://github.com/applegrew/django-select2.git
+cd django-select2/example
+python3 -m pip install -r requirements.txt
+python3 manage.py migrate
+python3 manage.py createsuperuser
+# follow the instructions to create a superuser
+python3 manage.py runserver
+# follow the instructions and open your browser
+```

example/README.md

@@ -0,0 +1,16 @@
+"""
+ASGI config for example project.
+
+It exposes the ASGI callable as a module-level variable named ``application``.
+
+For more information on this file, see
+https://docs.djangoproject.com/en/dev/howto/deployment/asgi/
+"""
+
+import os
+
+from django.core.asgi import get_asgi_application
+
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'example.settings')
+
+application = get_asgi_application()