Opened 4 years ago

Closed 4 years ago

#16264 closed Cleanup/optimization (fixed)

Improve widget documentation

Reported by: from_a_far@… Owned by: bpeschier
Component: Documentation Version: 1.3
Severity: Normal Keywords: docs
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

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)

Attachments (5)

django-16264.diff (14.6 KB) - added by bpeschier 4 years ago.
django-16264.2.diff (15.4 KB) - added by bpeschier 4 years ago.
django-16264.3.diff (16.3 KB) - added by bpeschier 4 years ago.
django-16264.4.diff (16.9 KB) - added by bpeschier 4 years ago.
django-16264.5.diff (18.2 KB) - added by julien 4 years ago.

Download all attachments as: .zip

Change History (21)

comment:1 Changed 4 years ago by julien

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted
  • Type changed from Uncategorized to Cleanup/optimization

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

comment:2 Changed 4 years ago by bpeschier

  • Owner changed from nobody to bpeschier
  • Summary changed from Simple Docs request to Improve widget documentation

comment:3 Changed 4 years ago by julien

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.

Changed 4 years ago by bpeschier

comment:4 Changed 4 years ago by bpeschier

  • Has patch set

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.

comment:5 Changed 4 years ago by julien

  • Patch needs improvement set

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.

Changed 4 years ago by bpeschier

comment:6 Changed 4 years ago by bpeschier

  • Patch needs improvement unset

Done :-)

comment:7 Changed 4 years ago by julien

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! :)

comment:8 Changed 4 years ago by julien

  • Patch needs improvement set

Changed 4 years ago by bpeschier

comment:9 Changed 4 years ago by bpeschier

  • Patch needs improvement unset

No problem!

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

comment:10 Changed 4 years ago by julien

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.

comment:11 Changed 4 years ago by julien

  • Patch needs improvement set

Changed 4 years ago by bpeschier

comment:12 Changed 4 years ago by bpeschier

  • Patch needs improvement unset

Used an example from SpliteDateTimeWidget to explain compress.

comment:13 Changed 4 years ago by 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)

Changed 4 years ago by julien

comment:14 Changed 4 years ago by julien

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.

comment:15 Changed 4 years ago by julien

  • Triage Stage changed from Accepted to Ready for checkin

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

comment:16 Changed 4 years ago by jezdez

  • Resolution set to fixed
  • Status changed from new to closed

In [16408]:

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

Note: See TracTickets for help on using tickets.
Back to Top