Add more comprehencive gettings started app and example

.gitignore

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

README.rst

@@ -1,68 +1,29 @@
+==============
 Django-Select2
 ==============
 
-|version| |ci| |coverage| |license|
+|version| |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(r'^select2/', include('django_select2.urls')),
-
 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

docs/conf.py

@@ -1,8 +1,11 @@
 import os
+import pathlib
 import sys
 
 from pkg_resources import get_distribution
 
+BASE_DIR = pathlib.Path(__file__).resolve(strict=True).parent.parent
+
 # This is needed since django_select2 requires django model modules
 # and those modules assume that django settings is configured and
 # have proper DB settings.
@@ -12,13 +15,13 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath("../tests.testapp"))
-sys.path.insert(0, os.path.abspath(".."))
+sys.path.insert(0, str(BASE_DIR / "tests" / "testapp"))
+sys.path.insert(0, str(BASE_DIR))
 
 
 project = "Django-Select2"
 author = "Johannes Hoppe"
-copyright = "2017, Johannes Hoppe"
+copyright = "2017-2020, Johannes Hoppe"
 release = get_distribution("django_select2").version
 version = ".".join(release.split(".")[:2])
 

docs/index.rst

@@ -1,7 +1,189 @@
-.. 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 URL root configuration:
+
+.. 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
+:class:`.DummyCache` or :class:`.LocMemCache`), 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_authored_by')
+
+
+Next, we create a model form with custom Select2 widgets.
+
+.. 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 CoAuthorsWidget(s2forms.ModelSelect2MultipleWidget):
+        search_fields = [
+            "username__icontains",
+            "email__icontains",
+        ]
+
+
+    class BookForm(forms.ModelForm):
+        class Meta:
+            model = models.Book
+            fields = "__all__"
+            widgets = {
+                "author": AuthorWidget,
+                "co_authors": CoAuthorsWidget,
+            }
+
+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
+        success_url = "/"
+
+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 method="POST">
+            {% csrf_token %}
+            {{ 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 +194,6 @@ Contents:
    :maxdepth: 2
    :glob:
 
-   get_started
    django_select2
    extra
    CONTRIBUTING