Improve widget documentation

[from_a_far@…]

This is my first ticket, so go easy.

When you type 'django widgets' into google the first page you get is > ​https://docs.djangoproject.com/en/dev/ref/forms/widgets/

While this describes the widgets in detail it does not cover application (specifically in my case 'RadioSelect'). It took me a 20mins+ of scouring to find the following > ​http://blog.entzeroth.com/2010/04/django-forms-widgets-that-could-use.html?showComment=1308143572439#c5724730594809830764. Which with it's simple snippet of code covered a lot of my questions.

Could this be added to the docs? Sorry for asking but I don't have time to learn two document systems and learn new markup. (sorry :( )

(I also get an overwhelming feeling I am posting this in completely the wrong place)

[Julien Phalip]

The widgets doc could certainly do with a simple, concrete example.

[Julien Phalip]

By the way, thanks for the report, you've come to the right place. It's always useful to get feedback from new users on how to improve the documentation.

[Bas Peschier]

Jumped in and created a patch for this.

• Reshuffles the sections to better show how the widgets are used.
• Brushed up some internal references and removed faulty docs (relating to the format on date and time widgets)
• Added an example and explanation about choices.

[Julien Phalip]

Excellent! Here are just a few minor remarks:

• Add a reference link to "see the documentation for the built-in Field classes".
• Show the required imports in the "Setting arguments for widgets" example.
• Add "code-block" directives to all examples.
• Add a tilda in front of the :class:'~django.forms.widgets.extras.SelectDateWidget' reference so that only SelectDateWidget gets displayed and to make it more digestible.
• Add double back-quotes around years in "the years attribute is set..." (or use an :attr: clause).
• In the "Widgets with choices" section, can you add references to the relevant widgets? "A couple of widgets deal with choices" is a bit vague.

[Bas Peschier]

Done :-)

[Julien Phalip]

Nice! I have few more small remarks:

• Can you add a tilda in front of :attr:'~SelectDateWidget.years'?
• The phrase "The reference below describes which options can be set." feels a bit out of place. It would sit better under the SimpleForm example, also including a link to the "Built-in widgets" section.
• Move the date field in SimpleForm to the top (i.e. above radio and checkboxes) and rename it year, so that it's identifiable more quickly.
• The "Widgets with choices" section could be made a little clearer. For example, "Widgets inheriting from the Select widget" would sound clearer than "Widgets based on the Select widget". Also "these are 'owned' by a field" feels a bit confusing. It'd be nice to also clarify the relationship between ChoiceField and and the Select widget (i.e. when/how are they used together). A code sample might also help, if you can add one.

Sorry to be so picky. Your patch is already really good and it's close to be RFC.

Thanks! :)

[Bas Peschier]

No problem!

Fixed a reference to CharField and mentioned format localization as well, while we are at it :-)

[Julien Phalip]

OK, I promise this is the last time I send it back :-)

• Rename choice to choice_field in the "Widgets inheriting from the Select widget" section's code sample.
• Clarify what "compress" or a "compressed" value means, in the "MultiWidget" section.
• Also in the "MultiWidget" section, use back-quotes and/or cross-references for types and method names.

[Bas Peschier]

Used an example from SpliteDateTimeWidget to explain compress.

[anonymous]

You guys are amazing! Thank you very much!

Just two things:

• Where can I see these changes (or do I need to install stuff and do repository/git things)
• Any chance the import locations (e.g. from django.forms.widgets import RadioSelect and from django.forms.extras.widgets import SelectDateWidget) can be included with description/examples. This would be seriously helpful to us new-bees. (Can't use stuff if you don't know how to get it)

[Julien Phalip]

OK, I've posted a new patch with PEP8's 80 characters limit (except for code samples), explicit imports as suggested in comment:13, more realistic field names and values for the SimpleForm example and a few more insignificant tweaks.

@anonymous: to see the changes you need to apply the attached patch to your checkout of Django trunk. See ​https://docs.djangoproject.com/en/dev/internals/contributing/writing-documentation/ for more details on how the doc works.

[Julien Phalip]

In concertation with bpeschier on IRC, this is good to go. Thanks for your awesome work!

[Jannis Leidel]

In [16408]:

Fixed #16264 -- Improved form widget documentation. Many thanks to Bas Peschier.