Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

#18451 Improved class based view documentation #144

Closed
wants to merge 90 commits into from
@pydanny

For https://code.djangoproject.com/ticket/18451

Ref Improvements:

  • Documentation moved to /ref/class-based-views/ directory.
  • Method Resolution Order (MRO) on most views.
  • Method flowchart added to many views.
  • Mixins moved to their own pages.
  • Mixins demonstrate which other Mixins they extend.
  • Autodoc added to all views and mixins.
    • Because the Django code does always not contain docstrings, or it is not complete, there remains in many cases the old manual documentation.
    • 'Note' statements placed whenever autodoc is in addition to manual documentation.

Topic Improvements:

  • Documentation moved to /topics/class-based-views/ directory.
  • Cleaner explanation including additional examples.
  • More examples.
  • Mixins moved to their own pages.
  • Very clean mixin documentation with advocacy for best practices.

Authors:

  • Daniel Greenfeld
  • James Aylett
  • Marc Tamlyn
  • Simon Williams
mjtamlyn and others added some commits
@mjtamlyn mjtamlyn Don't refer to all cbvs as 'generic views'. d9fbf40
@mjtamlyn mjtamlyn Text wrapping. f13a378
@mjtamlyn mjtamlyn Split up discussion of CBV and Generic CBV. 8967e70
@mjtamlyn mjtamlyn Templates can exist in multiple places. cf5d4ed
@mjtamlyn mjtamlyn Make example code use the subclassing pattern. 9b32d1e
@mjtamlyn mjtamlyn Move deiscussion of GCBVs into separate file. e63051f
@mjtamlyn mjtamlyn Separate reference documentation of cbvs and mixins. b4c4096
@mjtamlyn mjtamlyn Add stubs for other cbv topic areas. 84cb8c2
@pydanny pydanny Changed references to 'simple generic class based views' to 'Fundamen…
…tal class based views'. Also worked on some new dialogue to help explain things
a29adf2
@pydanny pydanny Finished removal of generic from description of fundamental class bas…
…ed views
323c9ec
@mjtamlyn mjtamlyn Promote and expand on when to stop. 3407c81
@pydanny pydanny Added much of what should hopefully be the new format for the View an…
…d TemplateView fundamental classes
0a2b8bf
@pydanny pydanny converted 'mixins' for fundamental classes to method resolution order 379af2a
@mjtamlyn mjtamlyn Best practices in list and detail views examples.
Try to make the examples more consistent and follow some best practices.
For example: all strings are single quoted, views are always defined via
subclassing, and certain 1.4 now features are given for reference rather
than re-implementing them.
296ee0f
@mjtamlyn mjtamlyn Put in a placeholder to reference other topics. 44796a1
@mjtamlyn mjtamlyn Better use of the timezeone aware now. 6c28263
@pydanny pydanny Finished documentation of fundamental views and also added working ex…
…ample code to all views
75ce4f5
@pydanny pydanny Fixed regular expression in urls.py example a646fca
@pydanny pydanny Added working version of View example fa22bb5
@jaylett jaylett Add new CBV & generic CBV topic documents into index. afbaef9
@jaylett jaylett Augment docstring to mention response_kwargs. 7cb8d3b
@jaylett jaylett Update JSONResponseMixin to match newer TemplateResponseMixin, and pr…
…ovide a ref target for that section.
af7519e
@jaylett jaylett Basic reference documentation of ContextMixin. 983b554
@jaylett jaylett Stage one of CBV mixin topic docs: what's there and how it's used in …
…the generic views.
9447a8a
@jaylett jaylett Fix up reference to generic views documentation. 8c06593
@pydanny pydanny Merge pull request #1 from jaylett/cbv-docs
Cbv docs changes provided by @jaylett
1e65f4b
@pydanny pydanny Temporary RST fix on a note b0ead02
Simon Williams Initial content for cbv form handling page b7215b4
Simon Williams Merge branch 'cbv-docs' of git://github.com/pydanny/django into cbv-docs c906dc1
@SystemParadox SystemParadox Added missing success_url for DeleteView 633fd1b
@pydanny pydanny Merge pull request #2 from SystemParadox/cbv-docs
Initial form handling CBV docs
f3e0445
@SystemParadox SystemParadox Merge branch 'cbv-docs' of git://github.com/pydanny/django into cbv-docs ae0aeba
@pydanny pydanny moved mention of the Base* views out of the generic CBV references an…
…d into a note section at the bottom
08f73a9
@jaylett jaylett Add some descriptions missing for core mixins.
Add "Methods & Attributes" headers throughout CBV mixin ref docs.
e4d063b
@SystemParadox SystemParadox Added note about form_class and model c2ae752
@SystemParadox SystemParadox Added example for created_by user handing in CreateView 0089cf0
@SystemParadox SystemParadox Merge branch 'cbv-docs' of git://github.com/pydanny/django into cbv-docs 22a6d87
@pydanny pydanny Implemented the first pass on the new autodoc system 65b2e08
@SystemParadox SystemParadox Improved documentation for form_valid 2157dc4
@pydanny pydanny Added views index 6775bbe
@pydanny pydanny Merge pull request #3 from SystemParadox/cbv-docs
CBV form docs
c3e4a43
@pydanny pydanny Changed CBV ref navigation to use a dedicated class-based-views direc…
…tory. This lets us break up the huge files into smaller, more digestible components
b2800a6
@jaylett jaylett Name the AuthorDetailView URL, and provide a target for one of the se…
…ctions.
58f6c49
@jaylett jaylett Three examples of using mixins with other CBVs.
Both the more-complex-than-View + mixin examples are suspicious, and reinforce the view that this is a bad idea. I'd probably favour dropping the FormMixin + DetailView example as unreadable and unhelpful.

The SingleObjectMixin + ListView requires a little thought, but is still just about manageable and is a helpful thing to be able to do. SingleObjectMixin + View is just fine.
1008dc9
@jaylett jaylett Merge remote branch 'refs/remotes/pydanny/cbv-docs' into cbv-docs 5eba978
@pydanny pydanny Added autoclass to generic-editing views 6e50c43
@pydanny pydanny corrected formatting to include proper section titles across generic …
…class based view refs
9effb21
@pydanny pydanny Added the mro.py prettification script at root of docs. Demonstrated …
…the results of the script by updating the MRO statements for fundamental, display, and edit class based views
7b9467e
@mjtamlyn mjtamlyn Merge branch 'cbv-docs' of git://github.com/pydanny/django into cbv-docs d13df05
@mjtamlyn mjtamlyn No more `"` and `'` mixing! 2ef458d
@pydanny pydanny Added in the date class based generic views MRO listings c0e7e43
James Aylett Move class based view topic docs into their own subtree, matching
the ref docs.
986f280
James Aylett Merge remote branch 'pydanny/cbv-docs' into cbv-docs f6d1d2c
@pydanny pydanny initial work on documenting the mixins 660dc51
James Aylett Take the most vile example of combining generic CBV functionality
and present it as something not to do; explain a couple of other
approaches of doing the same things which have fewer problems.
fc2c08e
James Aylett Merge remote branch 'pydanny/cbv-docs' into cbv-docs 92cb9f2
James Aylett Update to new ref doc place for CBV mixins. 93102be
James Aylett More explicit warnings, and light text fettling from pydanny. 6a0a067
@pydanny pydanny Merge pull request #6 from jaylett/cbv-docs
Mixins galore.
2076df7
@pydanny pydanny resolved merge conflict and also did a little cleanup on the mro script d75be87
@pydanny pydanny Broke up the mixins reference in order to make it more human friendly…
…. The files went into the same directory as the CBV refs in order to keep nesting at a minimum.
20af74b
James Aylett Link warning suitably. 8647a5a
James Aylett More cross linking, and some more explanation, in generic editing
CBV topic.
950cbb9
@pydanny pydanny Added note to Autodoc methods/attributes explaining that it's a work …
…in progress
be84676
@pydanny pydanny Merge pull request #7 from jaylett/cbv-docs
Cbv docs
6aa1f54
@pydanny pydanny Clarificaton that ProcessFormView is actually a mixin. 1a136cc
@pydanny pydanny Corrected spelling issues, removed empty generic-date-based CBV topic…
… file, and other minor cleanups
e697822
@mjtamlyn mjtamlyn Merge branch 'cbv-docs' of git://github.com/pydanny/django into cbv-docs b342b7d
@mjtamlyn mjtamlyn Moderate language regarding diy views.
As requested by @pydanny.
175b6ce
@pydanny pydanny Merge pull request #5 from mjtamlyn/cbv-docs
First run through improving the generic cbv topic.
bc40fc2
@pydanny pydanny Merge remote-tracking branch 'upstream/master' into cbv-docs 728dc2c
@pydanny pydanny Changed a TODO to a RST comment 9a37ed1
docs/ref/class-based-views.old
((350 lines not shown))
+ **Ancestors (MRO)**
+
+ * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
+ * :class:`django.views.generic.base.TemplateResponseMixin`
+ * :class:`django.views.generic.detail.BaseDetailView`
+ * :class:`django.views.generic.detail.SingleObjectMixin`
+ * :class:`django.views.generic.base.View`
+
+ **Method Flowchart**
+
+ 1. dispatch()
+ 2. http_method_not_allowed()
+ 3. get_template_names()
+ 4. get_slug_field()
+ 5. get_queryset()
+ 6. get_object
@mjtamlyn Collaborator
mjtamlyn added a note

Missing a () here (and some other similar places)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views.old
((304 lines not shown))
+
+ Constructs the target URL for redirection.
+
+ The default implementation uses :attr:`~RedirectView.url` as a starting
+ string, performs expansion of ``%`` parameters in that string, as well
+ as the appending of query string if requested by
+ :attr:`~RedirectView.query_string`. Subclasses may implement any
+ behavior they wish, as long as the method returns a redirect-ready URL
+ string.
+
+ **Autoclass methods**
+
+Generic views
+=============
+
+Django’s generic views were developed to ease that pain. They take certain
@spookylukey Collaborator

"that pain" - what pain?

@mjtamlyn Collaborator
mjtamlyn added a note

Sorry I'd split up some paragraphs and nor properly proof read them.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jacobian
Collaborator

Filling in some discussion from IRC:

I think this should nix the use of autodoc. autodoc isn't used in Django's docs deliberately: it prevents translation (which we want to do, despite have not done it...) and it can cause the docs to be hard to build (since it means they have to be able to import django, risking the dreaded DJANGO_SETTINGS_MODULE error). Instead, I'd like to see this use the include directive to avoid repetition.

kennethlove added some commits
@kennethlove kennethlove Updates to the edit views' docstrings.
Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
632b801
@kennethlove kennethlove Updates to the date views
Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
efe4601
@kennethlove kennethlove Updates to the base views
Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
1282938
@kennethlove kennethlove Updates to the detail views
Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
ba0e4c5
@kennethlove kennethlove Updates to the list views
Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
70b9b3a
docs/ref/class-based-views.old
@@ -0,0 +1,736 @@
+=================
+Class-based views
+=================
+
+.. versionadded:: 1.3
+
+.. note::
+ Prior to Django 1.3, class based views were implemented as functions. The

This line is incorrect; generic views were functions. Class based views weren't implemented.

@mjtamlyn Collaborator
mjtamlyn added a note

Agreed. This sentence makes no sense.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views.old
((26 lines not shown))
+Fundamental class based views
+=============================
+
+The following three classes provide much of the functionality needed to create
+Django views. You may think of them as *base* views, which can be used by
+themselves or inherited from. They may not provide all the capabilities required
+for projects, in which case there are Mixins and Generic class based views.
+
+Specification
+-------------
+
+Each request served by a class based view has an independent state; therefore,
+it is safe to store state variables on the instance (i.e., ``self.foo = 3`` is
+a thread-safe operation).
+
+A class-based view is deployed into a URL pattern using the

Interchanges class-based and class based
(side note: Does this warrant a distinct note in the Django specific terminology for documentation?)

@mjtamlyn Collaborator
mjtamlyn added a note

Hmm, which do you think is better. I guess class based.

@mjtamlyn Collaborator
mjtamlyn added a note

On second thoughts and after searching the existing docs it should be class-based. The release notes certainly always use this form. I'll update all references not just those in this section.

class-based would be proper grammer, just like we'd use Earth-based or faith-based.

@mjtamlyn Collaborator
mjtamlyn added a note

Fixed in 87b5513.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/fundamentals.txt
((30 lines not shown))
+ 2. http_method_not_allowed()
+
+
+ **Example views.py**::
+
+ from django.http import HttpResponse
+ from django.views.generic import View
+
+ class MyView(View):
+
+ def get(self, request, *args, **kwargs):
+ return HttpResponse('Hello, World!')
+
+ **Example urls.py**::
+
+ from django.conf.urls.defaults import patterns, url

This occurs in a few examples through-out the diff, but the references in the existing docs, as of 1.4 should be using from django.conf.urls import ..., though I can't find the ticket that updated them.

@mjtamlyn Collaborator
mjtamlyn added a note

Yup, I'd forgotten we had that updated import path.

@mjtamlyn Collaborator
mjtamlyn added a note

Fixed in b93208e

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@mjtamlyn
Collaborator

More updates from me can be found here: https://github.com/pydanny/django/pull/8. When @pydanny has accepted them they'll appear here.

@mjtamlyn mjtamlyn commented on the diff
docs/topics/class-based-views/mixins.txt
((582 lines not shown))
+
+Finally we bring this together in a new :class:`AuthorDetail` view. We
+already know that calling :meth:`as_view()` on a class based view
+gives us something that behaves exactly like a function based view, so
+we can do that at the point we choose between the two subviews.
+
+You can of course pass through keyword arguments to :meth:`as_view()`
+in the same way you would in your URLconf, such as if you wanted the
+:class:`AuthorInterest` behaviour to also appear at another URL but
+using a different template.
+
+.. code-block:: python
+
+ from django.views.generic import View
+
+ class AuthorDetail(View):
@mjtamlyn Collaborator
mjtamlyn added a note

My first reaction reading this was 'why not just write a functional view for this one, it's only 4 lines'. May be worth pointing out that (for example) this code with 405 to a PUT request.

Really nice example though.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@mjtamlyn mjtamlyn commented on the diff
docs/topics/class-based-views/mixins.txt
((550 lines not shown))
+ }
+ context.update(kwargs)
+ return super(AuthorDisplay, self).get_context_data(**context)
+
+Then the :class:`AuthorInterest` is a simple :class:`FormView`, but we
+have to bring in :class:`SingleObjectMixin` so we can find the author
+we're talking about, and we have to remember to set
+:attr:`template_name` to ensure that form errors will render the same
+template as :class:`AuthorDisplay` is using on ``GET``.
+
+.. code-block:: python
+
+ from django.views.generic import FormView
+ from django.views.generic.detail import SingleObjectMixin
+
+ class AuthorInterest(FormView, SingleObjectMixin):
@mjtamlyn Collaborator
mjtamlyn added a note

There's possibly some missing subtlety here. If an invalid POST is made to this view, object will not be in the context. We need to actually implement this little test app somewhere in order to ensure all of our example code behaves as predicted.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@mjtamlyn mjtamlyn commented on the diff
docs/topics/class-based-views/generic-editing.txt
@@ -0,0 +1,205 @@
@mjtamlyn Collaborator
mjtamlyn added a note

Need to think about how this interacts with the working with forms doc. There should be a reference back to this document from the other one. Unsurprisingly, there is a substantial difference in tone/verbosity between this doc and the mixins doc. It would be good to get a more cohesive feeling here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/generic-editing.txt
((88 lines not shown))
+First we need to add :meth:`get_absolute_url()` to our :class:`Author`
+class:
+
+.. code-block:: python
+
+ # models.py
+ from django import models
+ from django.core.urlresolvers import reverse
+
+ class Author(models.Model):
+ name = models.CharField(max_length=200)
+
+ def get_absolute_url(self):
+ return reverse(
+ 'author-detail',
+ kwargs = { 'pk': self.pk', },
@mjtamlyn Collaborator
mjtamlyn added a note

Syntax error! Extra ' after self.pk. Also we should be showing valid pep8 code - no spaces inside a dict literal.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/generic-editing.txt
((107 lines not shown))
+work. Notice how we're just configuring the generic class based views
+here; we don't have to write any logic ourselves::
+
+ # views.py
+ from myapp.models import Author
+ from django.views.generic.edit import CreateView, UpdateView, DeleteView
+
+ class AuthorCreate(CreateView):
+ model = Author
+
+ class AuthorUpdate(UpdateView):
+ model = Author
+
+ class AuthorDelete(DeleteView):
+ model = Author
+ success_url = '/authors/'
@mjtamlyn Collaborator
mjtamlyn added a note

If we're doing best practices here, this should be a lazy_reverse('authors_list') or something along those lines.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@dbrgn

Wow, sorry for the interruption, but thanks for your great documentation efforts! :)

docs/ref/class-based-views.old
@@ -0,0 +1,736 @@
+=================
+Class-based views
+=================
+
+.. versionadded:: 1.3
+
+.. note::
+ Prior to Django 1.3, class based views were implemented as functions. The
+ function-based implementation has been removed in favor of the
+ class-based approach described here.
+
+
+Writing Web applications can be monotonous, because we repeat certain patterns
@dbrgn
dbrgn added a note

Should "Web" really be capitalized? Same thing two lines below.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/fundamentals.txt
((61 lines not shown))
+
+ The ``view`` part of the view -- the method that accepts a ``request``
+ argument plus arguments, and returns a HTTP response.
+
+ The default implementation will inspect the HTTP method and attempt to
+ delegate to a method that matches the HTTP method; a ``GET`` will be
+ delegated to :meth:`~View.get()`, a ``POST`` to :meth:`~View.post()`,
+ and so on.
+
+ The default implementation also sets ``request``, ``args`` and
+ ``kwargs`` as instance variables, so any method on the view can know
+ the full details of the request that was made to invoke the view.
+
+ .. method:: http_method_not_allowed(request, *args, **kwargs)
+
+ If the view was called with HTTP method it doesn't support, this method
@dbrgn
dbrgn added a note

s/with HTTP method/with a HTTP method/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/fundamentals.txt
((99 lines not shown))
+ which is a dictionary of the parameters captured in the URL.
+
+ **Classpath**
+
+ ``django.views.generic.base.TemplateView``
+
+ **Ancestors (MRO)**
+
+ * :class:`django.views.generic.base.TemplateView`
+ * :class:`django.views.generic.base.TemplateResponseMixin`
+ * :class:`django.views.generic.base.View`
+
+ **Method Flowchart**
+
+ 1. dispatch()
+ 2. http_method_not_allowed()
@dbrgn
dbrgn added a note

Why http_method_not_allowed()? Shouldn't that rather be handler() or get() / post() / put() / ...?

Same thing applies for other Method Flowchart listings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/generic-display.txt
((28 lines not shown))
+ * :class:`django.views.generic.detail.BaseDetailView`
+ * :class:`django.views.generic.detail.SingleObjectMixin`
+ * :class:`django.views.generic.base.View`
+
+ **Method Flowchart**
+
+ 1. dispatch()
+ 2. http_method_not_allowed()
+ 3. get_template_names()
+ 4. get_slug_field()
+ 5. get_queryset()
+ 6. get_object
+ 7. get_context_object_name()
+ 8. get_context_data()
+ 9. get()
+ 10. render_to_response()
@dbrgn
dbrgn added a note

Something's wrong with this flowchart. get() is called right after the dispatch() method. http_method_not_allowed() should never be called, as mentioned in another comment above. get_object should be a function and should be executed after get().

@dbrgn
dbrgn added a note

Bump.

@pydanny
pydanny added a note

I like fundamental and agree with mjtamlyn.

As for flowcharts,

The flowcharts are purposefully in this simplified format for now and I request they stay in this format on this pull request. In other words, I would like it to be addressed in a future pull request. In fact, @jacobian says he has an idea for rendering them, and @idangazit should certainly be given his say. On a side note, I prefer Graphviz, but only out of familiarity.

As for their completeness, while I would like to get them to 100% right now, that is not a small amount of work. I think a better option is to accept this monolithic pull request sooner rather then later, then let the flow charts be handled in a smaller pull request or a series of them. That way they can be more easily audited and will allow more eyes on them, making a deep problem very shallow. :wink:

@idan Collaborator
idan added a note

Wow, wrapping my head around this gigantic thread. I love having Django on github.

I assume these must be renderable programmatically because there will be a lot of them. Must they be renderable at docs-creation time? Alternatively, if we can stipulate that they are renderable in-browser, that lets us do some nice things there (but makes PDF generation more complicated, for example.

Off the top of my head, there are three good options for rendering the charts:

  • Graphviz: simple, descriptive language for defining graph. Not much control over rendering output.
  • Nodebox: A graphics library for python, analogous to Processing. Nodebox-opengl seems pip-installable, need to see that this works on all platforms. Pros: majorly nice control over rendering output. Cons: commensurate headache.
  • D3 or other web charting/graphics libraries: a nice way to do it in-browser. Cons: only in-browser.

Right now the commit isn't clear on much of a flow, it's just a list of steps in order. Perhaps an IRC discussion to help me get my bearings would be helpful,

@idan Collaborator
idan added a note

Following up: I'm +1 on the docs containing a rough outline of operation in bullet-point form now, and improving things to add some graphical representation later. This is already a monster pull request, no need to hold it up for Just One More Addition.

@jezdez Owner
jezdez added a note

FYI, you are all commenting on a code line not on the pull request.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@dbrgn

I could probably help a little with those docs, but I don't want to conflict with currently ongoing work. Is anyone working on major changes?

Something I noticed is that the method flowcharts aren't always correct. I could for example verify and correct those.

Against which version are those docs written? 1.5-dev?

@mjtamlyn
Collaborator

Ok, autodoc is nixed. #145 has been merged in. Most of the small comments from here are fixed up, and the dead files (ref/class-based-views.old and mro.py) have been deleted.

So I think we're kinda there. There's still a load to do but it would make sense to get this merged in and then look for smaller patches to improve it further. Will make it much easier for others to get involved.

django/views/generic/edit.py
@@ -106,10 +119,17 @@ def get_success_url(self):
return url
def form_valid(self, form):
+ """
+ If the form is valid, save is associated model.
@jezdez Owner
jezdez added a note

Typo.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
django/views/generic/edit.py
@@ -125,11 +145,19 @@ class ProcessFormView(View):
A mixin that processes a form on POST.
"""
def get(self, request, *args, **kwargs):
+ """
+ Handles the GET HTTP verb and instantiates a blank version of the form.
@jezdez Owner
jezdez added a note

You mean "handles GET requests"?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
django/views/generic/edit.py
((7 lines not shown))
form_class = self.get_form_class()
form = self.get_form(form_class)
return self.render_to_response(self.get_context_data(form=form))
def post(self, request, *args, **kwargs):
+ """
+ Handles the POST HTTP verb, instantiating an instance of the class
@jezdez Owner
jezdez added a note

"Handles POST requests" please.

@jezdez Owner
jezdez added a note

"Instantiating a form instance with the passed POST variables, .." sounds simpler.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/conf.py
@@ -20,6 +20,10 @@
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "_ext")))
+sys.path.insert(0, os.path.abspath('../'))
@jezdez Owner
jezdez added a note

If all autodoc is removed now, we can remove this, too. Including the settings.configure() call.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/fundamentals.txt
@@ -0,0 +1,246 @@
+=============================
+Fundamental class-based views
+=============================
+
+The following three classes provide much of the functionality needed to create
+Django views. You may think of them as *base* views, which can be used by
+themselves or inherited from. They may not provide all the capabilities required
@jezdez Owner
jezdez added a note

Two spaces behind the punctuation?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/fundamentals.txt
((23 lines not shown))
+
+ from django.http import HttpResponse
+ from django.views.generic import View
+
+ class MyView(View):
+
+ def get(self, request, *args, **kwargs):
+ return HttpResponse('Hello, World!')
+
+ **Example urls.py**::
+
+ from django.conf.urls import patterns, url
+
+ from myapp.views import MyView
+
+ urlpatterns = patterns("",
@jezdez Owner
jezdez added a note

Let's use PEP8 code style here.

@mjtamlyn Collaborator
mjtamlyn added a note

God yes. It hurts my eyeses.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/fundamentals.txt
((170 lines not shown))
+
+ from django.shortcuts import get_object_or_404
+ from django.views.generic.base import RedirectView
+
+ from articles.models import Article
+
+ class ArticleCounterRedirectView(RedirectView):
+
+ permanent = True
+ query_string = True
+
+ def get_redirect_url(self, pk):
+ article = get_object_or_404(Article, pk=pk)
+ article.count += 1
+ article.save()
+ return reverse('product_detail', args=(pk, ))
@jezdez Owner
jezdez added a note

One space too much.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/fundamentals.txt
((168 lines not shown))
+
+ **Example views.py**::
+
+ from django.shortcuts import get_object_or_404
+ from django.views.generic.base import RedirectView
+
+ from articles.models import Article
+
+ class ArticleCounterRedirectView(RedirectView):
+
+ permanent = True
+ query_string = True
+
+ def get_redirect_url(self, pk):
+ article = get_object_or_404(Article, pk=pk)
+ article.count += 1
@jezdez Owner
jezdez added a note

The example is well-intended but maybe should do something else, or use the F object.

@mjtamlyn Collaborator
mjtamlyn added a note

Opted for calling an imaginary update_counter method on the article. Also set it to be non-permanent redirect otherwise it wouldn't be much use as a view (I believe the browser would skip hitting this url at all in future)

@jezdez Owner
jezdez added a note

Cool!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/generic-date-based.txt
((62 lines not shown))
+
+ Determine if an object list will be returned as part of the context. If
+ ``False``, the ``None`` queryset will be used as the object list.
+
+ **Context**
+
+ In addition to the context provided by
+ :class:`django.views.generic.list.MultipleObjectMixin` (via
+ :class:`django.views.generic.dates.BaseDateListView`), the template's
+ context will be:
+
+ * ``date_list``: A ``DateQuerySet`` object containing all months that
+ have objects available according to ``queryset``, represented as
+ ``datetime.datetime`` objects, in ascending order.
+
+ * ``year``: A ``datetime.date`` object representing the given year.
@jezdez Owner
jezdez added a note

We could use the intersphinx ability in Sphinx here to link to the Python docs.

@mjtamlyn Collaborator
mjtamlyn added a note

Would be nice. Couldn't seem to get it to work.

It looks like it's been set up to link to the python docs in the conf.py but :ref:datetime.date<python:anything-here> (with the necessary back ticks) was giving me an error:

WARNING: undefined label: python:datetime (if the link has no caption the label must precede a section header)

@jezdez Owner
jezdez added a note

Try :class:datetime.date

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/generic-date-based.txt
@@ -0,0 +1,275 @@
+====================================
+Generic date class-based views
+====================================
+
+Date-based generic views (in the module :mod:`django.views.generic.dates`)
+are views for displaying drilldown pages for date-based data.
+
+.. currentmodule:: django.views.generic.dates
+
+ArchiveIndexView
+~~~~~~~~~~~~~~~~
+.. class:: ArchiveIndexView()
@jezdez Owner
jezdez added a note

I don't think brackets are needed here for the class directive.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/generic-date-based.txt
((104 lines not shown))
+ * :class:`django.views.generic.dates.BaseMonthArchiveView`
+ * :class:`django.views.generic.dates.YearMixin`
+ * :class:`django.views.generic.dates.MonthMixin`
+ * :class:`django.views.generic.dates.BaseDateListView`
+ * :class:`django.views.generic.list.MultipleObjectMixin`
+ * :class:`django.views.generic.dates.DateMixin`
+ * :class:`django.views.generic.base.View`
+
+ **Context**
+
+ In addition to the context provided by
+ :class:`~django.views.generic.list.MultipleObjectMixin` (via
+ :class:`~django.views.generic.dates.BaseDateListView`), the template's
+ context will be:
+
+ * ``date_list``: A ``DateQuerySet`` object containing all days that
@jezdez Owner
jezdez added a note

Could we link to DateQuerySet here?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/generic-display.txt
((34 lines not shown))
+
+ **Example views.py**::
+
+ from datetime import datetime
+
+ from django.views.generic.detail import DetailView
+
+ from articles.models import Article
+
+ class ArticleDetailView(DetailView):
+
+ model = Article
+
+ def get_context_data(self, **kwargs):
+ context = super(ArticleDetailView, self).get_context_data(**kwargs)
+ context['now'] = datetime.now()
@jezdez Owner
jezdez added a note

We should discourage using datetime.now given the new timezone abilities in 1.4. Instead use django.utils.timezone.now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/index.txt
((13 lines not shown))
+ generic-editing
+ generic-date-based
+ mixins
+
+Specification
+-------------
+
+Each request served by a class-based view has an independent state; therefore,
+it is safe to store state variables on the instance (i.e., ``self.foo = 3`` is
+a thread-safe operation).
+
+A class-based view is deployed into a URL pattern using the
+:meth:`~View.as_view()` classmethod::
+
+ urlpatterns = patterns('',
+ (r'^view/$', MyView.as_view(size=42)),
@jezdez Owner
jezdez added a note

Indented wrong.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/index.txt
((26 lines not shown))
+
+ urlpatterns = patterns('',
+ (r'^view/$', MyView.as_view(size=42)),
+ )
+
+.. admonition:: Thread safety with view arguments
+
+ Arguments passed to a view are shared between every instance of a view.
+ This means that you shoudn't use a list, dictionary, or any other
+ variable object as an argument to a view. If you did, the actions of
+ one user visiting your view could have an effect on subsequent users
+ visiting the same view.
+
+Any argument passed into :meth:`~View.as_view()` will be assigned onto the
+instance that is used to service a request. Using the previous example,
+this means that every request on ``MyView`` is able to interrogate
@jezdez Owner
jezdez added a note

"use" instead of "interrogate"?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/index.txt
((33 lines not shown))
+ Arguments passed to a view are shared between every instance of a view.
+ This means that you shoudn't use a list, dictionary, or any other
+ variable object as an argument to a view. If you did, the actions of
+ one user visiting your view could have an effect on subsequent users
+ visiting the same view.
+
+Any argument passed into :meth:`~View.as_view()` will be assigned onto the
+instance that is used to service a request. Using the previous example,
+this means that every request on ``MyView`` is able to interrogate
+``self.size``.
+
+Fundamental vs Generic class-based views
+-----------------------------------------
+
+Fundamental class-based views can be thought of as *base* views, which can be
+used by themselves or inherited from. They may not provide all the
@jezdez Owner
jezdez added a note

Double space after dot.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/index.txt
((35 lines not shown))
+ variable object as an argument to a view. If you did, the actions of
+ one user visiting your view could have an effect on subsequent users
+ visiting the same view.
+
+Any argument passed into :meth:`~View.as_view()` will be assigned onto the
+instance that is used to service a request. Using the previous example,
+this means that every request on ``MyView`` is able to interrogate
+``self.size``.
+
+Fundamental vs Generic class-based views
+-----------------------------------------
+
+Fundamental class-based views can be thought of as *base* views, which can be
+used by themselves or inherited from. They may not provide all the
+capabilities required for projects, in which case there are Mixins which extend
+what Fundamental views can do.
@jezdez Owner
jezdez added a note

lower case for "Fundamental"?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/mixins-editing.txt
((13 lines not shown))
+ A dictionary containing initial data for the form.
+
+ .. attribute:: form_class
+
+ The form class to instantiate.
+
+ .. attribute:: success_url
+
+ The URL to redirect to when the form is successfully processed.
+
+ .. method:: get_initial()
+
+ Retrieve initial data for the form. By default, returns a copy of
+ :attr:`~django.views.generic.edit.FormMixin.initial`.
+
+ .. admonition:: Changed in 1.4
@jezdez Owner
jezdez added a note

I think this can also be expressed with a .. versionchanged:: 1.4 directive.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/mixins-editing.txt
((132 lines not shown))
+ Saves the form instance, sets the current object for the view, and
+ redirects to
+ :meth:`~django.views.generic.edit.FormMixin.get_success_url`.
+
+ .. method:: form_invalid()
+
+ Renders a response, providing the invalid form as context.
+
+.. class:: django.views.generic.edit.ProcessFormView
+
+ A mixin that provides basic HTTP GET and POST workflow.
+
+ .. note::
+
+ This is named 'ProcessFormView' and inherits directly from :class:`django.views.generic.base.View`,
+ but breaks if used independently. Therefore is actually a mixin.
@jezdez Owner
jezdez added a note

Typo in last sentence.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/mixins-single-object.txt
((94 lines not shown))
+ operating on. ``self.object`` will usually be, but is not required to be,
+ an instance of a Django model. It may be ``None`` if the view is in the
+ process of constructing a new instance.
+
+ **Extends**
+
+ * :class:`~django.views.generic.base.TemplateResponseMixin`
+
+ **Methods and Attributes**
+
+ .. attribute:: template_name_field
+
+ The field on the current object instance that can be used to determine
+ the name of a candidate template. If either ``template_name_field`` or
+ the value of the ``template_name_field`` on the current object instance
+ is ``None``, the object will not be interrogated for a candidate
@jezdez Owner
jezdez added a note

"interrogated"?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/generic-display.txt
((118 lines not shown))
+ from django.conf.urls import patterns, url, include
+ from books.views import PublisherList
+
+ urlpatterns = patterns('',
+ url(r'^publishers/$', PublisherList.as_view()),
+ )
+
+That's all the Python code we need to write. We still need to write a template,
+however. We could explicitly tell the view which template to use by adding a
+``template_name`` attribute to the view, but in the absence of an explicit
+template Django will infer one from the object's name. In this case, the
+inferred template will be ``"books/publisher_list.html"`` -- the "books" part
+comes from the name of the app that defines the model, while the "publisher"
+bit is just the lowercased version of the model's name.
+
+.. note:: Thus, when (for example) the :class:`django.template.loaders.app_directories.Loader` template loader is enabled in :setting:`TEMPLATE_LOADERS`, a template location could be: /path/to/project/books/templates/books/publisher_list.html
@jezdez Owner
jezdez added a note

Please wrap the lines of this note.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/generic-display.txt
((211 lines not shown))
+
+ class PublisherDetail(DetailView):
+
+ model = Publisher
+
+ def get_context_data(self, **kwargs):
+ # Call the base implementation first to get a context
+ context = super(PublisherDetailView, self).get_context_data(**kwargs)
+ # Add in a QuerySet of all the books
+ context['book_list'] = Book.objects.all()
+ return context
+
+.. note::
+
+ Generally, get_context_data will merge the context data of all parent classes
+ with those of the current class. To preserve this behavior in your own classes
@jezdez Owner
jezdez added a note

Two spaces after the dot.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez commented on the diff
docs/topics/class-based-views/generic-display.txt
((378 lines not shown))
+ salutation = models.CharField(max_length=10)
+ name = models.CharField(max_length=200)
+ email = models.EmailField()
+ headshot = models.ImageField(upload_to='/tmp')
+ last_accessed = models.DateTimeField()
+
+The generic ``DetailView`` class, of course, wouldn't know anything about this
+field, but once again we could easily write a custom view to keep that field
+updated.
+
+First, we'd need to add an author detail bit in the URLconf to point to a
+custom view::
+
+ from books.views import AuthorDetailView
+
+ urlpatterns = patterns('',
@jezdez Owner
jezdez added a note

PEP8 please.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/generic-editing.txt
((71 lines not shown))
+saves the model automatically. You can override this if you have any
+special requirements; see below for examples.
+
+You don't even need to provide a attr:`success_url` for
+:class:`~django.views.generic.edit.CreateView` or
+:class:`~django.views.generic.edit.UpdateView` - they will use
+:meth:`get_absolute_url()` on the model object if available.
+
+If you want to use a custom :class:`ModelForm` (for instance to add
+extra validation) simply set
+:attr:`~django.views.generic.edit.FormMixin.form_class` on your view.
+
+.. note::
+ When specifying a custom form class, you must still specify the model,
+ even though the :attr:`form_class` may be a :class:`ModelForm`.
+ (See https://code.djangoproject.com/ticket/15125)
@jezdez Owner
jezdez added a note

Not sure if linking a ticket is really sensible here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/generic-editing.txt
((108 lines not shown))
+ from django.views.generic.edit import CreateView, UpdateView, DeleteView
+ from django.core.urlresolvers import reverse_lazy
+ from myapp.models import Author
+
+ class AuthorCreate(CreateView):
+ model = Author
+
+ class AuthorUpdate(UpdateView):
+ model = Author
+
+ class AuthorDelete(DeleteView):
+ model = Author
+ success_url = reverse_lazy('author-list')
+
+.. note::
+ We have to use ``reverse_lazy`` here, not just ``reverse`` as the urls are
@jezdez Owner
jezdez added a note

Link to the reverse_lazy docs here?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/index.txt
((71 lines not shown))
+ from django.conf.urls import patterns, url, include
+ from django.views.generic import TemplateView
+
+ urlpatterns = patterns('',
+ (r'^about/', TemplateView.as_view(template_name="about.html")),
+ )
+
+A similar overriding pattern can be used for the ``url`` attribute on
+:class:`~django.views.generic.base.RedirectView`.
+
+.. _jsonresponsemixin-example:
+
+More than just HTML
+-------------------
+
+Where class based view shine is when you want to do the same thing many times.
@jezdez Owner
jezdez added a note

s/view/views/g

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/mixins.txt
((22 lines not shown))
+
+For this reason, Django also provides a number of mixins that provide
+more discrete functionality. Template rendering, for instance, is
+encapsulated in the
+:class:`~django.views.generic.base.TemplateResponseMixin`. The Django
+reference documentation contains :doc:`full documentation of all the
+mixins</ref/class-based-views/mixins>`.
+
+Context and template responses
+==============================
+
+Two central mixins are provided that help in providing a consistent
+interface to working with templates in class-based views.
+
+:class:`~django.views.generic.base.TemplateResponseMixin`
+ Everywhere that needs to make a
@jezdez Owner
jezdez added a note

"Everywhere that needs to make.." sounds odd to me.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/mixins.txt
((25 lines not shown))
+encapsulated in the
+:class:`~django.views.generic.base.TemplateResponseMixin`. The Django
+reference documentation contains :doc:`full documentation of all the
+mixins</ref/class-based-views/mixins>`.
+
+Context and template responses
+==============================
+
+Two central mixins are provided that help in providing a consistent
+interface to working with templates in class-based views.
+
+:class:`~django.views.generic.base.TemplateResponseMixin`
+ Everywhere that needs to make a
+ :class:`~django.template.response.TemplateResponse` will call the
+ :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
+ method that :class:`TemplateResponseMixin` provides. Most of the time
@jezdez Owner
jezdez added a note

Double space.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/mixins.txt
((49 lines not shown))
+
+ ``render_to_response`` itself calls
+ :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`,
+ which by default will just look up
+ :attr:`~django.views.generic.base.TemplateResponseMixin.template_name`
+ on the class-based view; two other mixins
+ (:class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`
+ and
+ :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`)
+ override this to provide more flexible defaults when dealing with
+ actual objects.
+
+.. versionadded:: 1.5
+
+:class:`~django.views.generic.base.ContextMixin`
+ Everywhere that needs context data, such as for rendering a
@jezdez Owner
jezdez added a note

"Everywhere that needs context data" sounds odd.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez commented on the diff
docs/topics/class-based-views/mixins.txt
((235 lines not shown))
+ from django.views.generic.detail import SingleObjectMixin
+ from books.models import Author
+
+ class RecordInterest(View, SingleObjectMixin):
+ """Records the current user's interest in an author."""
+ model = Author
+
+ def post(self, request, *args, **kwargs):
+ if not request.user.is_authenticated():
+ return HttpResponseForbidden()
+
+ # Look up the author we're interested in.
+ self.object = self.get_object()
+ # Actually record interest somehow here!
+
+ return HttpResponseRedirect(
@jezdez Owner
jezdez added a note

PEP8

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/mixins.txt
((259 lines not shown))
+out. The only bit of the view that needs to worry about using
+:class:`SingleObjectMixin` is where we want to look up the author
+we're interested in, which it just does with a simple call to
+``self.get_object()``. Everything else is taken care of for us by the
+mixin.
+
+We can hook this into our URLs easily enough:
+
+.. code-block:: python
+
+ # urls.py
+ from books.views import RecordInterest
+
+ urlpatterns = patterns('',
+ #...
+ **url(
@jezdez Owner
jezdez added a note

PEP8

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez
Owner

Except some optional intersphinx links this looks good to me. If there are no other reviews, I'd commit this tomorrow.

@mjtamlyn
Collaborator

@jezdez, master of intersphinx. I believe all outstanding blocking issues are resolved.

@jezdez
Owner

Those changes fixed the build for me: https://gist.github.com/2907251

@jezdez
Owner

Oh, I think I still have two issues:

  • The word "Fundamentals" for describing the base class based views seems a bit off to me. It may be my non-nativeness but it sounds like "Fundamentalists" which has a rather negative connotation. I know "base" is also pretty loaded, so what if we call it "Basic class based views". Alternatively "Essential class based views"?

  • The method flowcharts need some nice graphics, or at least links to the appropriate methods instead of just a list of text.

Given those two important things are still open, I won't merge this just yet. Any help with solving would be much appreciated.

@mjtamlyn
Collaborator

Hmmm. I like fundamental. To me there's no connection with fundamentalist, and we're using it in the meaning of "Foundational" (which is a worse word) - kinda meaning that they're the important ones and the ones upon which everything else is built. Basic has connotations of simple, and I'm not sure they are... Essential also implies you have to use them, which you don't.

Flowcharts are a bit more of a question. I probably need to do a good review of them to make sure they're actually accurate. Some graphviz graphics would be nice, but I'm concerned about them not being updated properly. Either we build them first and commit the images to the repo, or we use http://sphinx.pocoo.org/ext/graphviz.html to build them dynamically. This would require everything to have the relevant binaries installed though. Opinions @jacobian?

A lot of the ref docs are incomplete - which includes the method flows. Not every method is documented yet (see previous discussion about includes/autodoc) - I've not written all of the replacement references now the autobuilt stuff is gone. Do we want to get it all accurate and finished before we merge anything?

Re those build changes, I'm not getting errors but that is tidier rst so I'll make those tweaks.

@pydanny

@idangazit I'm going to find you on IRC. Right now.

@pydanny pydanny closed this
@pydanny pydanny reopened this
@jezdez
Owner

I'm going to close this as I think it's ready for commit (I have all the changes locally). I've decided to not go with fundamental as I think it would introduce more confusion. But that's really a minor thing and I'm happy to say this is going to be a HUGE help for our users. Thank you good sirs.

@jezdez jezdez closed this
@idan
Collaborator

:cake::sparkles:

@bryanhelmig

Just in time to make us look foolish (http://3rdaverad.io/shows/django-podcast/episodes/class-vs-function-based-views/) as we complain about lack of documentation... :-D

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Jun 7, 2012
  1. @mjtamlyn
  2. @mjtamlyn

    Text wrapping.

    mjtamlyn authored
  3. @mjtamlyn
  4. @mjtamlyn
  5. @mjtamlyn
  6. @mjtamlyn
  7. @mjtamlyn
  8. @mjtamlyn
  9. @pydanny

    Changed references to 'simple generic class based views' to 'Fundamen…

    pydanny authored
    …tal class based views'. Also worked on some new dialogue to help explain things
  10. @pydanny
  11. @mjtamlyn
  12. @pydanny

    Added much of what should hopefully be the new format for the View an…

    pydanny authored
    …d TemplateView fundamental classes
  13. @pydanny
  14. @mjtamlyn

    Best practices in list and detail views examples.

    mjtamlyn authored
    Try to make the examples more consistent and follow some best practices.
    For example: all strings are single quoted, views are always defined via
    subclassing, and certain 1.4 now features are given for reference rather
    than re-implementing them.
  15. @mjtamlyn
  16. @mjtamlyn
  17. @pydanny
  18. @pydanny
  19. @pydanny
  20. @jaylett

    Add new CBV & generic CBV topic documents into index.

    jaylett authored James Aylett committed
  21. @jaylett

    Augment docstring to mention response_kwargs.

    jaylett authored James Aylett committed
  22. @jaylett

    Update JSONResponseMixin to match newer TemplateResponseMixin, and pr…

    jaylett authored James Aylett committed
    …ovide a ref target for that section.
  23. @jaylett

    Basic reference documentation of ContextMixin.

    jaylett authored James Aylett committed
  24. @jaylett

    Stage one of CBV mixin topic docs: what's there and how it's used in …

    jaylett authored James Aylett committed
    …the generic views.
  25. @jaylett

    Fix up reference to generic views documentation.

    jaylett authored James Aylett committed
  26. @pydanny

    Merge pull request #1 from jaylett/cbv-docs

    pydanny authored
    Cbv docs changes provided by @jaylett
  27. @pydanny

    Temporary RST fix on a note

    pydanny authored
  28. Initial content for cbv form handling page

    Simon Williams authored
  29. @SystemParadox
  30. @pydanny

    Merge pull request #2 from SystemParadox/cbv-docs

    pydanny authored
    Initial form handling CBV docs
  31. @SystemParadox
  32. @pydanny

    moved mention of the Base* views out of the generic CBV references an…

    pydanny authored
    …d into a note section at the bottom
  33. @jaylett

    Add some descriptions missing for core mixins.

    jaylett authored
    Add "Methods & Attributes" headers throughout CBV mixin ref docs.
  34. @SystemParadox
  35. @SystemParadox
  36. @SystemParadox
  37. @pydanny
  38. @SystemParadox
  39. @pydanny

    Added views index

    pydanny authored
  40. @pydanny
  41. @pydanny

    Changed CBV ref navigation to use a dedicated class-based-views direc…

    pydanny authored
    …tory. This lets us break up the huge files into smaller, more digestible components
  42. @jaylett
  43. @jaylett

    Three examples of using mixins with other CBVs.

    jaylett authored
    Both the more-complex-than-View + mixin examples are suspicious, and reinforce the view that this is a bad idea. I'd probably favour dropping the FormMixin + DetailView example as unreadable and unhelpful.
    
    The SingleObjectMixin + ListView requires a little thought, but is still just about manageable and is a helpful thing to be able to do. SingleObjectMixin + View is just fine.
  44. @jaylett
Commits on Jun 8, 2012
  1. @pydanny
  2. @pydanny
  3. @pydanny

    Added the mro.py prettification script at root of docs. Demonstrated …

    pydanny authored
    …the results of the script by updating the MRO statements for fundamental, display, and edit class based views
  4. @mjtamlyn
  5. @mjtamlyn

    No more `"` and `'` mixing!

    mjtamlyn authored
  6. @pydanny
  7. Move class based view topic docs into their own subtree, matching

    James Aylett authored
    the ref docs.
  8. Merge remote branch 'pydanny/cbv-docs' into cbv-docs

    James Aylett authored
  9. @pydanny
  10. Take the most vile example of combining generic CBV functionality

    James Aylett authored
    and present it as something not to do; explain a couple of other
    approaches of doing the same things which have fewer problems.
  11. Merge remote branch 'pydanny/cbv-docs' into cbv-docs

    James Aylett authored
  12. Update to new ref doc place for CBV mixins.

    James Aylett authored
  13. @pydanny

    Merge pull request #6 from jaylett/cbv-docs

    pydanny authored
    Mixins galore.
  14. @pydanny
  15. @pydanny

    Broke up the mixins reference in order to make it more human friendly…

    pydanny authored
    …. The files went into the same directory as the CBV refs in order to keep nesting at a minimum.
  16. Link warning suitably.

    James Aylett authored
  17. More cross linking, and some more explanation, in generic editing

    James Aylett authored
    CBV topic.
  18. @pydanny
  19. @pydanny
  20. @pydanny
  21. @pydanny

    Corrected spelling issues, removed empty generic-date-based CBV topic…

    pydanny authored
    … file, and other minor cleanups
  22. @mjtamlyn
  23. @mjtamlyn

    Moderate language regarding diy views.

    mjtamlyn authored
    As requested by @pydanny.
  24. @pydanny

    Merge pull request #5 from mjtamlyn/cbv-docs

    pydanny authored
    First run through improving the generic cbv topic.
  25. @pydanny
  26. @pydanny
  27. @kennethlove

    Updates to the edit views' docstrings.

    kennethlove authored
    Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
  28. @kennethlove

    Updates to the date views

    kennethlove authored
    Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
  29. @kennethlove

    Updates to the base views

    kennethlove authored
    Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
  30. @kennethlove

    Updates to the detail views

    kennethlove authored
    Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
  31. @kennethlove

    Updates to the list views

    kennethlove authored
    Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
  32. @mjtamlyn
  33. @mjtamlyn
  34. @mjtamlyn

    Fix some weird sentences.

    mjtamlyn authored
  35. @mjtamlyn
Commits on Jun 9, 2012
  1. @mjtamlyn
  2. @mjtamlyn

    Tidy up topic pages.

    mjtamlyn authored
    Remove broken refs, clarify a little text, fix and pep8 some code
    examples.
  3. @mjtamlyn

    Delete old files.

    mjtamlyn authored
  4. @mjtamlyn

    Fix a grammatical error.

    mjtamlyn authored
  5. @mjtamlyn

    Remove autodoc.

    mjtamlyn authored
  6. @mjtamlyn
  7. @mjtamlyn
Commits on Jun 10, 2012
  1. @mjtamlyn
  2. @mjtamlyn

    RST tidyup.

    mjtamlyn authored
Something went wrong with that request. Please try again.