From acef399098506d0b51436378709b302eda7a2042 Mon Sep 17 00:00:00 2001 From: mfrasca Date: Fri, 3 May 2019 10:20:31 -0500 Subject: [PATCH 01/14] expanding docs, adding sphinx makefile --- docs/Makefile | 19 +++++++++++++++++++ docs/get_started.rst | 24 ++++++++++++++++++------ 2 files changed, 37 insertions(+), 6 deletions(-) create mode 100644 docs/Makefile diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..298ea9e2 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/get_started.rst b/docs/get_started.rst index d545c79f..7e729723 100644 --- a/docs/get_started.rst +++ b/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 ``, +* 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 ----------- @@ -31,13 +43,13 @@ 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:: + :class:`Select2MultipleWidget <.django_select2.forms.Select2MultipleWidget>`, + replacing:: class MyForm(forms.Form): things = ModelMultipleChoiceField(queryset=Thing.objects.all()) -with:: + with:: from django_select2.forms import Select2MultipleWidget From 79c301e0247766c3bd8b4a8bc2b5316f1055ef01 Mon Sep 17 00:00:00 2001 From: mfrasca Date: Fri, 3 May 2019 18:31:12 -0500 Subject: [PATCH 02/14] more explicit docs --- docs/get_started.rst | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/docs/get_started.rst b/docs/get_started.rst index 7e729723..e0d08170 100644 --- a/docs/get_started.rst +++ b/docs/get_started.rst @@ -42,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 - :class:`Select2MultipleWidget <.django_select2.forms.Select2MultipleWidget>`, - replacing:: - - class MyForm(forms.Form): - things = ModelMultipleChoiceField(queryset=Thing.objects.all()) - - with:: - - from django_select2.forms import Select2MultipleWidget - - class MyForm(forms.Form): - things = ModelMultipleChoiceField(queryset=Thing.objects.all(), widget=Select2MultipleWidget) +1. Replace native Django forms widgets with one of the several ``django_select2`` form widgets. + Start by importing them into your forms.py:: + + from django import forms + from django_select2 import forms as s2forms + + 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:: + + widgets = { + 'category': s2forms.Select2Widget, + 'author': s2forms.ModelSelect2Widget(model=auth.get_user_model(), + search_fields=['first_name', 'last_name', 'username', 'email']), + 'attending': s2forms.ModelSelect2MultipleWidget … + } 2. Add the CSS to the ``head`` of your Django template:: From d77d0b3987c39190d30d592268a4a3ffee7a8ee9 Mon Sep 17 00:00:00 2001 From: mfrasca Date: Fri, 3 May 2019 18:34:08 -0500 Subject: [PATCH 03/14] simplifying the text. --- docs/get_started.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/get_started.rst b/docs/get_started.rst index e0d08170..725d832d 100644 --- a/docs/get_started.rst +++ b/docs/get_started.rst @@ -42,8 +42,8 @@ Here is a quick example to get you started: 0. Follow the installation instructions above. -1. Replace native Django forms widgets with one of the several ``django_select2`` form widgets. - Start by importing them into your forms.py:: +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:: from django import forms from django_select2 import forms as s2forms @@ -55,7 +55,7 @@ Here is a quick example to get you started: widgets = { 'category': s2forms.Select2Widget, 'author': s2forms.ModelSelect2Widget(model=auth.get_user_model(), - search_fields=['first_name', 'last_name', 'username', 'email']), + search_fields=['first_name', 'last_name']), 'attending': s2forms.ModelSelect2MultipleWidget … } From d1e9df5d23aed0b6918937cf2e78c9a68a43232a Mon Sep 17 00:00:00 2001 From: mfrasca Date: Sat, 4 May 2019 07:32:36 -0500 Subject: [PATCH 04/14] related to #542 and #543 --- docs/get_started.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/get_started.rst b/docs/get_started.rst index 725d832d..145411f9 100644 --- a/docs/get_started.rst +++ b/docs/get_started.rst @@ -55,7 +55,7 @@ Here is a quick example to get you started: widgets = { 'category': s2forms.Select2Widget, 'author': s2forms.ModelSelect2Widget(model=auth.get_user_model(), - search_fields=['first_name', 'last_name']), + search_fields=['first_name__istartswith', 'last_name__icontains']), 'attending': s2forms.ModelSelect2MultipleWidget … } From 71ff4df9f89310cf429b67e92b0f52b8b513a532 Mon Sep 17 00:00:00 2001 From: mfrasca Date: Mon, 13 May 2019 08:10:02 -0500 Subject: [PATCH 05/14] there are two types of widgets (and the list contains three). --- django_select2/forms.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/django_select2/forms.py b/django_select2/forms.py index 75b29568..2a014842 100644 --- a/django_select2/forms.py +++ b/django_select2/forms.py @@ -20,10 +20,11 @@ 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, @@ -31,15 +32,15 @@ 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 From 695c985375c683daf5235e46f029d2e2100d812b Mon Sep 17 00:00:00 2001 From: mfrasca Date: Mon, 13 May 2019 08:15:14 -0500 Subject: [PATCH 06/14] state that djangoSelect2 replaces select2 --- docs/django_select2.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/django_select2.rst b/docs/django_select2.rst index ebd36d51..cbb4d35e 100644 --- a/docs/django_select2.rst +++ b/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 `_ if $('.django-select2').djangoSelect2({placeholder: 'Select an option'}); +Please replace all your ``.select2`` invocations with the here provided +``.djangoSelect2``. + Security & Authentication ------------------------- From 05616afbb4f7af3f24ef18e4bec4aba4ac0aa192 Mon Sep 17 00:00:00 2001 From: mfrasca Date: Mon, 13 May 2019 08:50:46 -0500 Subject: [PATCH 07/14] removed as described --- docs/Makefile | 19 ------------------- 1 file changed, 19 deletions(-) delete mode 100644 docs/Makefile diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 298ea9e2..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file From 75fc6cd4c42e693c25feb53be2b322c7c275833a Mon Sep 17 00:00:00 2001 From: mfrasca Date: Mon, 13 May 2019 08:51:15 -0500 Subject: [PATCH 08/14] making a start at hints to developers --- docs/developers.rst | 15 +++++++++++++++ docs/index.rst | 1 + 2 files changed, 16 insertions(+) create mode 100644 docs/developers.rst diff --git a/docs/developers.rst b/docs/developers.rst new file mode 100644 index 00000000..c9074618 --- /dev/null +++ b/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+. + diff --git a/docs/index.rst b/docs/index.rst index b0e8051d..e2ae6618 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,6 +15,7 @@ Contents: get_started django_select2 extra + developers Indices and tables ================== From 70ca7b2486d9b5ff20497b0290405a63eada95a4 Mon Sep 17 00:00:00 2001 From: mfrasca Date: Mon, 13 May 2019 08:51:50 -0500 Subject: [PATCH 09/14] ignore emacs backups --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 2c9d9656..954050cd 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +*~ *.pyc Django_Select2.egg-info From b618ee97fcce36d2882d78105fbd68d7f926d180 Mon Sep 17 00:00:00 2001 From: Mario Frasca Date: Fri, 17 May 2019 07:10:17 -0500 Subject: [PATCH 10/14] Apply suggestions from code review Co-Authored-By: Johannes Hoppe --- docs/get_started.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/get_started.rst b/docs/get_started.rst index 145411f9..a61d4db8 100644 --- a/docs/get_started.rst +++ b/docs/get_started.rst @@ -11,7 +11,7 @@ Overview Assumptions ----------- -* You have a Django project, possibly with models linked by foreign key fields, +* You have a running Django project, possibly with models linked by foreign key fields, * are using Python3, * set up a virtual environment with ``python3 -m venv ``, * activated the virtual environment, From ca57ebf30704d52deea4fc65148c433a0b167f54 Mon Sep 17 00:00:00 2001 From: Mario Frasca Date: Fri, 17 May 2019 07:11:03 -0500 Subject: [PATCH 11/14] Apply suggestions from code review Co-Authored-By: Johannes Hoppe --- docs/get_started.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/get_started.rst b/docs/get_started.rst index a61d4db8..b83fd539 100644 --- a/docs/get_started.rst +++ b/docs/get_started.rst @@ -43,13 +43,13 @@ Here is a quick example to get you started: 0. Follow the installation instructions above. 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:: + Start by importing them into your ``forms.py``, right next to Django own ones:: from django import forms from django_select2 import forms as s2forms - 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 + Then let's assume you have a model with a choice, a :class:`.ForeignKey`, and a + :class:`.ManyToManyField`, you would add this information to your Form Meta class:: widgets = { From 2984192e679389d04ff7c5380f9472a00a6aa862 Mon Sep 17 00:00:00 2001 From: Johannes Hoppe Date: Fri, 13 Dec 2019 14:33:34 +0100 Subject: [PATCH 12/14] Apply review changes --- .gitignore | 1 - CONTRIBUTING.rst | 22 ++++++++++++++++++++++ docs/CONTRIBUTING.rst | 1 + docs/developers.rst | 15 --------------- docs/index.rst | 2 +- 5 files changed, 24 insertions(+), 17 deletions(-) create mode 100644 CONTRIBUTING.rst create mode 100644 docs/CONTRIBUTING.rst delete mode 100644 docs/developers.rst diff --git a/.gitignore b/.gitignore index 954050cd..2c9d9656 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,3 @@ -*~ *.pyc Django_Select2.egg-info diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..d3ccb2e0 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,22 @@ +Contributing +============ + +This package uses the pyTest test runner. To run the tests locally simply run:: + + python setup.py test + +If you need to the development dependencies installed of you local IDE, you can run:: + + python setup.py develop + +Documentation pull requests welcome. The Sphinx documentation can be compiled via:: + + 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. + +The list of supported Django and Python version can be found in the CI suite setup. +Please make sure to verify that none of the linters or tests failed, before you submit +a patch for review. diff --git a/docs/CONTRIBUTING.rst b/docs/CONTRIBUTING.rst new file mode 100644 index 00000000..e582053e --- /dev/null +++ b/docs/CONTRIBUTING.rst @@ -0,0 +1 @@ +.. include:: ../CONTRIBUTING.rst diff --git a/docs/developers.rst b/docs/developers.rst deleted file mode 100644 index c9074618..00000000 --- a/docs/developers.rst +++ /dev/null @@ -1,15 +0,0 @@ -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+. - diff --git a/docs/index.rst b/docs/index.rst index e2ae6618..dedf2e97 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,7 +15,7 @@ Contents: get_started django_select2 extra - developers + CONTRIBUTING Indices and tables ================== From 945b3f5596d24733bb51883ecffc9648922190a3 Mon Sep 17 00:00:00 2001 From: Johannes Hoppe Date: Fri, 13 Dec 2019 14:36:29 +0100 Subject: [PATCH 13/14] Shorten assuptions --- docs/get_started.rst | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/docs/get_started.rst b/docs/get_started.rst index b83fd539..58dbb589 100644 --- a/docs/get_started.rst +++ b/docs/get_started.rst @@ -11,14 +11,9 @@ Overview Assumptions ----------- -* You have a running Django project, possibly with models linked by foreign key fields, -* are using Python3, -* set up a virtual environment with ``python3 -m venv ``, -* 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. - +* You have a running Django up and running. +* You have form fully working without Django-Select2. + Installation ------------ From 25197fc4cfd54c3f483ba417c0cbc5529df3a484 Mon Sep 17 00:00:00 2001 From: Johannes Hoppe Date: Fri, 13 Dec 2019 14:39:42 +0100 Subject: [PATCH 14/14] Switch docs build do Python 3.7 --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index dac4f0c0..d3e75cd1 100644 --- a/.travis.yml +++ b/.travis.yml @@ -41,7 +41,7 @@ stages: jobs: include: - - python: "3.5" + - python: "3.7" env: TOXENV=docs addons: apt: