Opened 10 years ago

Closed 6 years ago

Last modified 5 years ago

#3469 closed (fixed)

Django.utils is not documented

Reported by: Chris Beaven Owned by: Joshua Russo
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 Russell Keith-Magee)

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 Joshua Russo 6 years ago.
Documented django.utils modules listed within API stability section
3469.diff (17.1 KB) - added by Ramiro Morales 6 years ago.
Rupe's patch with some reST fixes and tweaks. Great work!
3469-1.1.X.diff (17.1 KB) - added by Ramiro Morales 6 years ago.
Patch ported to 1.1.X branch

Download all attachments as: .zip

Change History (17)

comment:1 Changed 10 years ago by anonymous

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

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

Triage Stage: UnreviewedDesign decision needed

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

comment:3 Changed 9 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 9 years ago by Jacob

Triage Stage: Design decision neededSomeday/Maybe

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

comment:5 Changed 8 years ago by Russell Keith-Magee

Description: modified (diff)
Summary: DotExpandedDict is not documentedDjango.utils is not documented

comment:6 Changed 8 years ago by Malcolm Tredinnick

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 7 years ago by Chris Heisel

Owner: changed from nobody to Chris Heisel

comment:8 Changed 7 years ago by Chris Heisel

Owner: changed from Chris Heisel to nobody

comment:9 Changed 6 years ago by Joshua Russo

Owner: changed from nobody to Joshua Russo
Status: newassigned

comment:10 Changed 6 years ago by Joshua Russo

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 6 years ago by Joshua Russo

Attachment: django_utils_ref.diff added

Documented django.utils modules listed within API stability section

comment:11 Changed 6 years ago by Joshua Russo

milestone: 1.2

It would be nice to see this in 1.2

Changed 6 years ago by Ramiro Morales

Attachment: 3469.diff added

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

Changed 6 years ago by Ramiro Morales

Attachment: 3469-1.1.X.diff added

Patch ported to 1.1.X branch

comment:12 Changed 6 years ago by Ramiro Morales

Triage Stage: Someday/MaybeReady for checkin

Amazing work by Rupe, marking as RFC

comment:13 Changed 6 years ago by Brian Rosner

Resolution: fixed
Status: assignedclosed

(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 5 years ago by Jacob

milestone: 1.2

Milestone 1.2 deleted

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