Opened 8 years ago

Closed 5 years ago

Last modified 3 years ago

#3469 closed (fixed)

Django.utils is not documented

Reported by: SmileyChris Owned by: Rupe
Component: Documentation Version: master
Severity: Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: UI/UX:

Description (last modified by russellm)

There are a lot of useful utilities and datastructures in django.utils, but the lack of good user documentation limits the extent to which these utilities are used.

For example, DotExpandedDict is a useful but undocumented data structure. It can be very helpful for complex form parsing and it'd be good to mention somewhere in documentation.

Attachments (3)

django_utils_ref.diff (17.4 KB) - added by Rupe 5 years ago.
Documented django.utils modules listed within API stability section
3469.diff (17.1 KB) - added by ramiro 5 years ago.
Rupe's patch with some reST fixes and tweaks. Great work!
3469-1.1.X.diff (17.1 KB) - added by ramiro 5 years ago.
Patch ported to 1.1.X branch

Download all attachments as: .zip

Change History (17)

comment:1 Changed 8 years ago by anonymous

  • Needs documentation set
  • Needs tests unset
  • Patch needs improvement unset

comment:2 Changed 8 years ago by Michael Radziej <mir@…>

  • Triage Stage changed from Unreviewed to Design decision needed

@core: Do we want to document the various classes and functions in django.utils?

comment:3 Changed 7 years ago by emperorcezar

I think this one in particular needs documentation as it's very useful to a typical end user. I know that I had to ask in the IRC channel to find it originally.

comment:4 Changed 7 years ago by jacob

  • Triage Stage changed from Design decision needed to Someday/Maybe

Eventually, yes, the general-purpose datastructures in django.utils ought to get documentation.

comment:5 Changed 6 years ago by russellm

  • Description modified (diff)
  • Summary changed from DotExpandedDict is not documented to Django.utils is not documented

comment:6 Changed 6 years ago by mtredinnick

A note to whomever works on this: remember that large portions of django.utils are not considered to be public API, since. Django is a web framework, not a colleation general purpose data structure utilities (we just happen to use some general purpose utilities internally). So we don't guarantee API stability or even future availability and any docs should reflect that. The api-stability document describes where the dividing line lies.

comment:7 Changed 5 years ago by cmheisel

  • Owner changed from nobody to cmheisel

comment:8 Changed 5 years ago by cmheisel

  • Owner changed from cmheisel to nobody

comment:9 Changed 5 years ago by Rupe

  • Owner changed from nobody to Rupe
  • Status changed from new to assigned

comment:10 Changed 5 years ago by Rupe

  • Has patch set
  • Needs documentation unset
  • Patch needs improvement set

Ok, I consider this to be a first pass. It's pretty much all copy-n-paste out of comments and for SortedDict the Wiki. I did try to be relatively smart about it, paying attention to the all lists where appropriate and not including other unnecessary clutter. With that said, this should be very complete but should probably have someone who is not me to review.

Changed 5 years ago by Rupe

Documented django.utils modules listed within API stability section

comment:11 Changed 5 years ago by Rupe

  • milestone set to 1.2

It would be nice to see this in 1.2

Changed 5 years ago by ramiro

Rupe's patch with some reST fixes and tweaks. Great work!

Changed 5 years ago by ramiro

Patch ported to 1.1.X branch

comment:12 Changed 5 years ago by ramiro

  • Triage Stage changed from Someday/Maybe to Ready for checkin

Amazing work by Rupe, marking as RFC

comment:13 Changed 5 years ago by brosner

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

(In [13140]) Fixed #3469 -- added django.utils documentation for stable bits

Thanks to Rupe and Ramiro Morales for their initial work on this patch.

comment:14 Changed 3 years ago by jacob

  • milestone 1.2 deleted

Milestone 1.2 deleted

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