Documentation for CBV's?
Victor Hooi
I might be stating the obvious, but the documentation for the newer CBV's is a little sparse:
There's simple examples:
https://docs.djangoproject.com/en/1.3/topics/class-based-views/
As well as a generic list of mix-ins and in-built views:
https://docs.djangoproject.com/en/1.3/ref/class-based-views/
However, there's no fuller examples, or best practice notes. There's no explanation of any of the views beyond TemplateView, ListView and DetailView (e.g. UpdateView, DeleteView, RedirectView, or any of the date-based CBVs).
Sure, if you trawl around, you'll find some examples:
https://gist.github.com/1275204
https://groups.google.com/d/topic/django-users/HdYBkywNeII/discussion
http://stackoverflow.com/questions/5899810/class-based-view-extending-updateview-not-saving-form-correctlyhttp://stackoverflow.com/questions/6181041/updating-user-model-in-django-with-class-based-updateview
However, it would be awesome if there were examples in the official Django documentation that set out once and for all how to use these new-fangled CBV's. I would love to use them more extensively, but it seems like I'd need to spend hours on Google to work out all the nuances.
Is this something that could be resolved before pushing out Django 1.4, or is it much lower on the list of priorities?
Cheers,
Victor
Russell Keith-Magee
> Hi,
>
> I might be stating the obvious, but the documentation for the newer CBV's is
> a little sparse:
>
> There's simple examples:
>
> https://docs.djangoproject.com/en/1.3/topics/class-based-views/
>
> As well as a generic list of mix-ins and in-built views:
>
> https://docs.djangoproject.com/en/1.3/ref/class-based-views/
>
> However, there's no fuller examples, or best practice notes. There's no
> explanation of any of the views beyond TemplateView, ListView and DetailView
> (e.g. UpdateView, DeleteView, RedirectView, or any of the date-based CBVs).
>
> Sure, if you trawl around, you'll find some examples:
>
> https://gist.github.com/1275204
> https://groups.google.com/d/topic/django-users/HdYBkywNeII/discussion
> http://stackoverflow.com/questions/5899810/class-based-view-extending-updateview-not-saving-form-correctlyhttp://stackoverflow.com/questions/6181041/updating-user-model-in-django-with-class-based-updateview
>
> However, it would be awesome if there were examples in the official Django
> documentation that set out once and for all how to use these new-fangled
> CBV's. I would love to use them more extensively, but it seems like I'd need
> to spend hours on Google to work out all the nuances.
To use an old favourite phrase: ... and a pony :-)
I have to bear the bulk of the responsibility for this. The CBV docs
that I committed would be charitably described as "barely adequate".
There is *lots* of room for improvement -- both in terms of organizing
what is already there, and adding extra documentation, such as
tutorials and howtos.
However, what I don't have is an abundance of spare time to address
these inadequacies. :-(
> Is this something that could be resolved before pushing out Django 1.4, or
> is it much lower on the list of priorities?
It certainly *could* be resolved. If a ready-to-use patch were
available right now, I doubt it would sit in triage for very long --
the problems with the CBV docs are a well known sore point.
However, we don't have such a patch. As always, what is missing is
someone with the time and inclination to do the work.
The good news is that this isn't an area where an expert is required
-- this is an area where anyone could step up and provide a patch. In
fact, a patch from a beginner would possibly be preferable, because
they don't come to the process with any preconceived ideas of what is
obvious and what needs explanation.
So - if anyone wants to get involved with contributing to Django, this
could be a great project. You don't even need to be too concerned
about exact language. The hard part of writing is always the first
draft, because you need to work out gross structure, examples, and so
on. Once a first draft exists, second and later drafts are much
easier.
If someone were to provide a strong first draft of improved CBV docs
(and got someone else in the community to review that draft), I
suspect that draft would receive some editorial attention from the
core team and find itself in trunk very quickly.
Yours,
Russ Magee %-)
ptone
This is an area where I've done some work, though there is still much
to do.
I started with https://code.djangoproject.com/ticket/16807 at the
sprints, and need to wrap that up.
As far as an outline of modular, relatively atomic changes to the docs
that would be good to see:
* The above work on 16807 split into 2 parts, some integrated into an
revamped introduction to views, and more technical bits into a CBV
specific doc. This involves reworking the doc that introduce the very
concept of views, something that introduces the view contract,
function based views, then CBV.
* I've submitted an alternate/additional index to the reference
material that I think is clearer for users of the generic views in:
https://code.djangoproject.com/ticket/17378
* It would be great to see a CBV cookbook full of examples such as
auth login_required, Forms, etc
There are several CBV tickets I'm hoping to see closed for 1.4, which
while not documentation, will hopefully make CBV use a little clearer:
Tobias and I worked on https://code.djangoproject.com/ticket/16074 and
it is close to done
https://code.djangoproject.com/ticket/16744 follows easily after that
lands
and then https://code.djangoproject.com/ticket/17228 and
https://code.djangoproject.com/ticket/17381
those all help clean up the context story
It would be nice to see some resolution to https://code.djangoproject.com/ticket/14512,
I think the mixin approach is the best, but not sure the work can be
done to convert the rest of the stock decorators in time for 1.4?
Victor - are you interested in helping with this? Anyone else?
-Preston
On Dec 11, 10:27 pm, Victor Hooi <victorh...@gmail.com> wrote:
> Hi,
>
> I might be stating the obvious, but the documentation for the newer CBV's
> is a little sparse:
>
> There's simple examples:
>
> https://docs.djangoproject.com/en/1.3/topics/class-based-views/
>
> As well as a generic list of mix-ins and in-built views:
>
> https://docs.djangoproject.com/en/1.3/ref/class-based-views/
>
> However, there's no fuller examples, or best practice notes. There's no
> explanation of any of the views beyond TemplateView, ListView and
> DetailView (e.g. UpdateView, DeleteView, RedirectView, or any of the
> date-based CBVs).
>
> Sure, if you trawl around, you'll find some examples:
>
Victor Hooi
I don't know if I'm either qualified enough or knowledgeable enough on Django's core to contribute substantially to the documentation itself...lol.
However, I am happy to offer whatever I can - whether that means proofing drafts, contributing a beginner's viewpoint, or walking through a tutorial, I'm game to do that.
Preston - What do you think is the best way for others to collaborate/comment on your CBV docs? Should we be forking your fork on Github again? Or would you be amenable to using something like Google Docs or Wave for this?
(We'd need to convert back to RST afterwards, but it makes does make small simultaneous edits/comments among lots of people very easy)
https://docs.google.com/document/d/1z2zUVAo2csol9y6tUxMSoYWa65Wr9xtehRQ7GiMGyIg/edit
https://docs.google.com/document/d/18veral-ajxjMh0ZaU0wy5Sg5p9sqFMp5X3-8CuIM31A/edit
I've made a couple of small corrections to the Class Based Views doc - you can see them at File, See revision history, Show more detailed revisions.
Is this the sort of thing you mean?
Cheers,
Victor
Russell Keith-Magee
> Russ Magee/Preston:
>
> I don't know if I'm either qualified enough or knowledgeable enough on
> Django's core to contribute substantially to the documentation itself...lol.
Everyone has to begin somewhere, and documentation is a great place to
start. The best thing about contributing to the documentation of an
open source project is that if you don't know something, you can go
read the code until you do :-)
Yours,
Russ Magee %-)