Opened 17 years ago

Closed 14 years ago

Last modified 12 years ago

#3469 closed (fixed)

Django.utils is not documented

Reported by: Chris Beaven Owned by: Joshua Russo
Component: Documentation Version: dev
Severity: Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: no UI/UX: no

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 14 years ago.
Documented django.utils modules listed within API stability section
3469.diff (17.1 KB ) - added by Ramiro Morales 14 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 14 years ago.
Patch ported to 1.1.X branch

Download all attachments as: .zip

Change History (17)

comment:1 by anonymous, 17 years ago

Needs documentation: set

comment:2 by Michael Radziej <mir@…>, 17 years ago

Triage Stage: UnreviewedDesign decision needed

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

comment:3 by emperorcezar, 17 years ago

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 by Jacob, 16 years ago

Triage Stage: Design decision neededSomeday/Maybe

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

comment:5 by Russell Keith-Magee, 16 years ago

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

comment:6 by Malcolm Tredinnick, 16 years ago

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

Owner: changed from nobody to Chris Heisel

comment:8 by Chris Heisel, 15 years ago

Owner: changed from Chris Heisel to nobody

comment:9 by Joshua Russo, 14 years ago

Owner: changed from nobody to Joshua Russo
Status: newassigned

comment:10 by Joshua Russo, 14 years ago

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.

by Joshua Russo, 14 years ago

Attachment: django_utils_ref.diff added

Documented django.utils modules listed within API stability section

comment:11 by Joshua Russo, 14 years ago

milestone: 1.2

It would be nice to see this in 1.2

by Ramiro Morales, 14 years ago

Attachment: 3469.diff added

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

by Ramiro Morales, 14 years ago

Attachment: 3469-1.1.X.diff added

Patch ported to 1.1.X branch

comment:12 by Ramiro Morales, 14 years ago

Triage Stage: Someday/MaybeReady for checkin

Amazing work by Rupe, marking as RFC

comment:13 by Brian Rosner, 14 years ago

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 by Jacob, 12 years ago

milestone: 1.2

Milestone 1.2 deleted

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