Class Based Views Documentation

Disclaimer: this is a work in progress. Please fell free to add, object, expand the ideas listed below.

This wiki page will try to summarize were we stand regarding CBV documentation and what approaches we can take to improve it.

Class Based Views (not generic) Documentation

• Right now there's no documentation at all regarding not generic Class Based Views. They are as valid as function views for writing custom views.
• We should have a page linked from ​https://docs.djangoproject.com/en/dev/#the-view-layer in the same level as View Functions (which really is topics/http/views). Maybe change the name to Writing views (as the real page title) and include both function based and class based views. Or we can add a new page about writing class based views. Here we could explain the control flow of the CBV. Some little examples as with functions views docs would be nice. Also we could explain the concept of Mixins here with a simple example. In this page we could explain the difference between function and class based views, each pros and cons so the user can choose how to work.
• Work has been done in #16807, we should review it and propose changes.

Generic Class Based Views Documentation

• The reference is too much to take in. It just starts with the Mixins and then it goes on with the views. A reorganization would be in order and we might also need some kind of visual aid to better understand the Mixins / Views hierarchy. Otherwise the entry barrier is just to high.
• We could explain how the Views are laid out in the source; documentation is nice, but the final reference is in the code.
• Simplify the topic in more pages, at least move part of the topic to the non generic docs.
• Shout out that this are generic views, you won't be able to do everything with this views. The user will still need to create custom views for complex views.

Other sections of the docs

• In the actual topic doc we have a JSONResponseMixin. We might be able to extend this to another page and add examples about outputting CSV and PDF with mixins: ​https://docs.djangoproject.com/en/1.4/howto/outputting-pdf/ ​https://docs.djangoproject.com/en/1.4/howto/outputting-pdf/ . At least explain it's possible. Something like ​https://github.com/rasca/django-enhanced-cbv/blob/master/enhanced_cbv/views/base.py#L4 comes to mind.

External Efforts

There are a number of webistes that are offering documentation. These may well be worth reviewing and seeing what ideas we can build on. It seems to be a common blog post topic at the moment.

• ​http://ccbv.co.uk/
• ​http://www.caktusgroup.com/blog/2011/12/29/class-based-views-django-13/
• ​http://reinout.vanrees.org/weblog/2011/08/24/class-based-views-usage.html

Open Tickets

• #15730 RequestFactory Example Doesn't Address Class-Based Views
• #14829 URL dispatcher documentation with class-based generic views
• #16807 Document/Introduce the process and usage of class based views outside of generic view context
• #16970 calling as_view of CBV in URLConf needs better documentation and examples
• #17378 add "squashed" index of CBV reference documentation