more structured quick start #542

mfrasca · 2019-05-03T23:54:15Z

I've been trying to get django-select2 to work in my setup, but there's something missing and I don't quite understand what it is. in an attempt to understand things more clearly, I've written a less quick quick start, which was very much 'kort door de bocht' (that's Dutch, but the English "blunt" doesn't quite give the impression).

first of all, I've put back the missing sphinx Makefile.

I've added an Assumptions section before the Installation instructions.

next, I've given three examples, the first one works fine, the second almost, the third I've not completed. I think that the three of them are useful, for they exemplify three different situations.

I've removed the alternative style, defining fields directly in the class: I have not managed to get this to work at all.

I will open an issue about "the second almost" works.

codecov-io · 2019-05-03T23:58:50Z

Codecov Report

Merging #542 into master will not change coverage.
The diff coverage is n/a.

@@          Coverage Diff          @@
##           master   #542   +/-   ##
=====================================
  Coverage     100%   100%           
=====================================
  Files           2      2           
  Lines           8      8           
=====================================
  Hits            8      8

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2bb6f3a...d77d0b3. Read the comment docs.

codecov-io · 2019-05-03T23:58:50Z

Codecov Report

Merging #542 into master will not change coverage.
The diff coverage is n/a.

@@          Coverage Diff          @@
##           master   #542   +/-   ##
=====================================
  Coverage     100%   100%           
=====================================
  Files           2      2           
  Lines           8      8           
=====================================
  Hits            8      8

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2bb6f3a...ca57ebf. Read the comment docs.

codingjoe

Hi @mfrasca thank you for your contribution. Documentation improvements are always much appreciated. Let me know if you have further questions. I am happy to merge this, once you made some minor adjustments.

codingjoe · 2019-05-13T08:49:46Z

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation


I don't see how this is related to your PR. Please drop the chance. If you want to build the docs, please use python setup.py build_sphinx

how this is related to a documentation PR … without the Makefile, and without attempting python setup.py build_sphinx, it was unpractical to suggest corrections in the documentation. some are purely typesetting, and wanted to make sure that sphinx understood the formatting, because part of the output was a bit out of sync.
do you insist, in not having the Makefile in the docs? it doesn't do any harm, does it? anyway, I will double check that the choice is properly documented ("if you want to build the docs, please use python setup.py build_sphinx).

codingjoe · 2019-05-13T08:50:51Z

docs/get_started.rst

+* are using Python3,
+* set up a virtual environment with ``python3 -m venv <location>``,
+* activated the virtual environment,
+* installed ``django`` using ``pip``,


Django is a dependency of this package. So you don't necessarily need to install it. However, you do need an app setup.
Also, you may use pipenv, pip is not hard requirement.

I hadn't ever heard of pipenv, but I read »The official recommended way [to install pipenv] is to use pip«.

assumption: »you have a Django app«?

Pipenv is a whole toolset. You can use it to describe the entire environment including checksums, to ensure your environments are the same across machines. You should try it out!

Besides that, maybe better: you have a running Django app

codingjoe · 2019-05-13T08:53:00Z

docs/get_started.rst

+Assumptions
+-----------
+
+* You have a Django project, possibly with models linked by foreign key fields,


That is the main scenario, but not all of them. Maybe it makes sense to coin it, so it is clear that the library does support other scenarios.

I"m not sure I understand your comment. what about you edit the assumptions as to make them more correct, after you accept the PR?

codingjoe · 2019-05-13T08:55:35Z

docs/get_started.rst

-        class MyForm(forms.Form):
-            things = ModelMultipleChoiceField(queryset=Thing.objects.all())
+     from django import forms
+     from django_select2 import forms as s2forms


Good call to include the imports. I always forget 👍

codingjoe · 2019-05-13T08:56:37Z

docs/get_started.rst

-            things = ModelMultipleChoiceField(queryset=Thing.objects.all(), widget=Select2MultipleWidget)
+        widgets = {
+            'category': s2forms.Select2Widget,
+            'author': s2forms.ModelSelect2Widget(model=auth.get_user_model(),


You did not import auth, I would also suggest to import get_user_model directly instead, since you don't use anything else from the auth module.

codingjoe · 2019-05-13T08:57:07Z

docs/get_started.rst

-        
-        class MyForm(forms.Form):
-            things = ModelMultipleChoiceField(queryset=Thing.objects.all(), widget=Select2MultipleWidget)
+        widgets = {


Please include the entire code example, otherwise people will be confused.

I haven't written it yet. I'll review the PR in its entirety, and come back to you soon (36h).

36h went by, and I'm still busy on the project I'm working at. (mfrasca/ghini)
sooner or later, from that project, I will again need to dive into djangoSelect2, and I will again read the docs and amend the docs where what I will be reading doesn't make sense to me.
in particular, I will need the Multiple select widget, which I've not yet used.

codingjoe

Cool, I like how much effort you are putting into this. I absolutely appreciate it. Good documentation is key to open source.

codingjoe · 2019-05-17T07:25:15Z

docs/django_select2.rst


        $('.django-select2').djangoSelect2({placeholder: 'Select an option'});

+Please replace all your ``.select2`` invocations with the here provided


Suggested change

Please replace all your ``.select2`` invocations with the here provided

Please replace your ``.select2`` invocations with the here provided

docs/get_started.rst

codingjoe · 2019-05-17T07:52:46Z

docs/developers.rst

@@ -0,0 +1,15 @@
+Hints to Developers


Hi, good idea to add that. Please a CONTRIBUTING.rst file to the repo root and include it in here.

The contributing file is also supported by GitHub and will be displayed when someone opens a PR.

codingjoe · 2019-05-17T07:53:03Z

.gitignore

@@ -1,3 +1,4 @@
+*~


I'm a emacs user, I put this one everywhere.

Ok, I prefer to only have language or build specific things the .gitignore file. If you have things that are specific to your local environment, please put them into your global gitignore.

did not know of this option. thank you, it's useful.

Co-Authored-By: Johannes Hoppe <[email protected]>

mfrasca added 3 commits May 3, 2019 10:20

expanding docs, adding sphinx makefile

acef399

more explicit docs

79c301e

simplifying the text.

d77d0b3

mfrasca mentioned this pull request May 4, 2019

trying to get the docs straight #543

Closed

related to applegrew#542 and applegrew#543

d1e9df5

codingjoe requested changes May 13, 2019

View reviewed changes

codingjoe assigned codingjoe and mfrasca May 13, 2019

codingjoe added the documentation label May 13, 2019

mfrasca added 5 commits May 13, 2019 08:10

there are two types of widgets (and the list contains three).

71ff4df

state that djangoSelect2 replaces select2

695c985

removed as described

05616af

making a start at hints to developers

75fc6cd

ignore emacs backups

70ca7b2

codingjoe reviewed May 17, 2019

View reviewed changes

mfrasca and others added 5 commits May 17, 2019 07:10

Apply suggestions from code review

b618ee9

Co-Authored-By: Johannes Hoppe <[email protected]>

Apply suggestions from code review

ca57ebf

Co-Authored-By: Johannes Hoppe <[email protected]>

Apply review changes

2984192

Shorten assuptions

945b3f5

Switch docs build do Python 3.7

25197fc

codingjoe merged commit d63f410 into applegrew:master Dec 13, 2019


		$('.django-select2').djangoSelect2({placeholder: 'Select an option'});

		Please replace all your ``.select2`` invocations with the here provided

	Please replace all your ``.select2`` invocations with the here provided
	Please replace your ``.select2`` invocations with the here provided

more structured quick start #542

more structured quick start #542

Uh oh!

Conversation

mfrasca commented May 3, 2019

Uh oh!

codecov-io commented May 3, 2019

Codecov Report

Uh oh!

codecov-io commented May 3, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

codingjoe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codingjoe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov-io commented May 3, 2019 •

edited

Loading