Skip to content

#18451 Improved class based view documentation #144

Closed
wants to merge 90 commits into from
@pydanny
pydanny commented Jun 8, 2012

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 Jun 7, 2012
@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
@mjtamlyn mjtamlyn commented on an outdated diff Jun 8, 2012
docs/ref/class-based-views.old
+ **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
Django member
mjtamlyn added a note Jun 8, 2012

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
@spookylukey spookylukey and 1 other commented on an outdated diff Jun 8, 2012
docs/ref/class-based-views.old
+
+ 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
Django member
spookylukey added a note Jun 8, 2012

"that pain" - what pain?

@mjtamlyn
Django member
mjtamlyn added a note Jun 8, 2012

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
Django member
jacobian commented Jun 8, 2012

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 Jun 8, 2012
@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
@kezabelle kezabelle and 1 other commented on an outdated diff Jun 8, 2012
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
@kezabelle
kezabelle added a note Jun 8, 2012

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

@mjtamlyn
Django member
mjtamlyn added a note Jun 8, 2012

Agreed. This sentence makes no sense.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@kezabelle kezabelle and 2 others commented on an outdated diff Jun 8, 2012
docs/ref/class-based-views.old
+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
@kezabelle
kezabelle added a note Jun 8, 2012

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

@mjtamlyn
Django member
mjtamlyn added a note Jun 8, 2012

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

@mjtamlyn
Django member
mjtamlyn added a note Jun 8, 2012

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.

@kennethlove
kennethlove added a note Jun 8, 2012

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

@mjtamlyn
Django member
mjtamlyn added a note Jun 8, 2012

Fixed in 87b5513.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@kezabelle kezabelle and 1 other commented on an outdated diff Jun 8, 2012
docs/ref/class-based-views/fundamentals.txt
+ 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
@kezabelle
kezabelle added a note Jun 8, 2012

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
Django member
mjtamlyn added a note Jun 8, 2012

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

@mjtamlyn
Django member
mjtamlyn added a note Jun 8, 2012

Fixed in b93208e

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@mjtamlyn
Django member
mjtamlyn commented Jun 8, 2012

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 Jun 8, 2012
docs/topics/class-based-views/mixins.txt
+
+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
Django member
mjtamlyn added a note Jun 8, 2012

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 Jun 8, 2012
docs/topics/class-based-views/mixins.txt
+ }
+ 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
Django member
mjtamlyn added a note Jun 8, 2012

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 Jun 8, 2012
docs/topics/class-based-views/generic-editing.txt
@@ -0,0 +1,205 @@
@mjtamlyn
Django member
mjtamlyn added a note Jun 8, 2012

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
@mjtamlyn mjtamlyn commented on an outdated diff Jun 8, 2012
docs/topics/class-based-views/generic-editing.txt
+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
Django member
mjtamlyn added a note Jun 8, 2012

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
@mjtamlyn mjtamlyn commented on an outdated diff Jun 8, 2012
docs/topics/class-based-views/generic-editing.txt
+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
Django member
mjtamlyn added a note Jun 8, 2012

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
dbrgn commented Jun 9, 2012

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

@dbrgn dbrgn and 1 other commented on an outdated diff Jun 9, 2012
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 Jun 9, 2012

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
@dbrgn dbrgn commented on an outdated diff Jun 9, 2012
docs/ref/class-based-views/fundamentals.txt
+
+ 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 Jun 9, 2012

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
@dbrgn dbrgn commented on an outdated diff Jun 9, 2012
docs/ref/class-based-views/fundamentals.txt
+ 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 Jun 9, 2012

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
@dbrgn dbrgn and 3 others commented on an outdated diff Jun 9, 2012
docs/ref/class-based-views/generic-display.txt
+ * :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 Jun 9, 2012

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 Jun 10, 2012

Bump.

@pydanny
pydanny added a note Jun 11, 2012

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
Django member
idan added a note Jun 11, 2012

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
Django member
idan added a note Jun 11, 2012

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
Django member
jezdez added a note Jun 11, 2012

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
dbrgn commented Jun 9, 2012

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
Django member
mjtamlyn commented Jun 9, 2012

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.

@jezdez jezdez commented on an outdated diff Jun 9, 2012
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
Django member
jezdez added a note Jun 9, 2012

Typo.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez commented on an outdated diff Jun 9, 2012
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
Django member
jezdez added a note Jun 9, 2012

You mean "handles GET requests"?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez commented on an outdated diff Jun 9, 2012
django/views/generic/edit.py
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
Django member
jezdez added a note Jun 9, 2012

"Handles POST requests" please.

@jezdez
Django member
jezdez added a note Jun 9, 2012

"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
@jezdez jezdez commented on an outdated diff Jun 9, 2012
@@ -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
Django member
jezdez added a note Jun 9, 2012

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
@jezdez jezdez commented on an outdated diff Jun 9, 2012
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
Django member
jezdez added a note Jun 9, 2012

Two spaces behind the punctuation?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez and 1 other commented on an outdated diff Jun 9, 2012
docs/ref/class-based-views/fundamentals.txt
+
+ 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
Django member
jezdez added a note Jun 9, 2012

Let's use PEP8 code style here.

@mjtamlyn
Django member
mjtamlyn added a note Jun 9, 2012

God yes. It hurts my eyeses.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/ref/class-based-views/fundamentals.txt
+
+ 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
Django member
jezdez added a note Jun 9, 2012

One space too much.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez and 1 other commented on an outdated diff Jun 9, 2012
docs/ref/class-based-views/fundamentals.txt
+
+ **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
Django member
jezdez added a note Jun 9, 2012

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

@mjtamlyn
Django member
mjtamlyn added a note Jun 9, 2012

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
Django member
jezdez added a note Jun 9, 2012

Cool!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez and 1 other commented on an outdated diff Jun 9, 2012
docs/ref/class-based-views/generic-date-based.txt
+
+ 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
Django member
jezdez added a note Jun 9, 2012

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

@mjtamlyn
Django member
mjtamlyn added a note Jun 9, 2012

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
Django member
jezdez added a note Jun 9, 2012

Try :class:datetime.date

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez commented on an outdated diff Jun 9, 2012
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
Django member
jezdez added a note Jun 9, 2012

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
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/ref/class-based-views/generic-date-based.txt
+ * :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
Django member
jezdez added a note Jun 9, 2012

Could we link to DateQuerySet here?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/ref/class-based-views/generic-display.txt
+
+ **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
Django member
jezdez added a note Jun 9, 2012

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
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/ref/class-based-views/index.txt
+ 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
Django member
jezdez added a note Jun 9, 2012

Indented wrong.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/ref/class-based-views/index.txt
+
+ 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
Django member
jezdez added a note Jun 9, 2012

"use" instead of "interrogate"?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/ref/class-based-views/index.txt
+ 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
Django member
jezdez added a note Jun 9, 2012

Double space after dot.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/ref/class-based-views/index.txt
+ 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
Django member
jezdez added a note Jun 9, 2012

lower case for "Fundamental"?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/ref/class-based-views/mixins-editing.txt
+ 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
Django member
jezdez added a note Jun 9, 2012

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
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/ref/class-based-views/mixins-editing.txt
+ 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
Django member
jezdez added a note Jun 9, 2012

Typo in last sentence.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/ref/class-based-views/mixins-single-object.txt
+ 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
Django member
jezdez added a note Jun 9, 2012

"interrogated"?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/topics/class-based-views/generic-display.txt
+ 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
Django member
jezdez added a note Jun 9, 2012

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
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/topics/class-based-views/generic-display.txt
+
+ 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
Django member
jezdez added a note Jun 9, 2012

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 Jun 9, 2012
docs/topics/class-based-views/generic-display.txt
+ 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
Django member
jezdez added a note Jun 9, 2012

PEP8 please.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/topics/class-based-views/generic-editing.txt
+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
Django member
jezdez added a note Jun 9, 2012

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
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/topics/class-based-views/generic-editing.txt
+ 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
Django member
jezdez added a note Jun 9, 2012

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
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/topics/class-based-views/index.txt
+ 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
Django member
jezdez added a note Jun 9, 2012

s/view/views/g

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/topics/class-based-views/mixins.txt
+
+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
Django member
jezdez added a note Jun 9, 2012

"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
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/topics/class-based-views/mixins.txt
+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
Django member
jezdez added a note Jun 9, 2012

Double space.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/topics/class-based-views/mixins.txt
+
+ ``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
Django member
jezdez added a note Jun 9, 2012

"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 Jun 9, 2012
docs/topics/class-based-views/mixins.txt
+ 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
Django member
jezdez added a note Jun 9, 2012

PEP8

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez jezdez commented on an outdated diff Jun 9, 2012
docs/topics/class-based-views/mixins.txt
+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
Django member
jezdez added a note Jun 9, 2012

PEP8

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jezdez
Django member
jezdez commented Jun 9, 2012

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

@mjtamlyn
Django member

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

@jezdez
Django member
jezdez commented Jun 10, 2012

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

@jezdez
Django member
jezdez commented Jun 10, 2012

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
Django member

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
pydanny commented Jun 11, 2012

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

@pydanny pydanny closed this Jun 11, 2012
@pydanny pydanny reopened this Jun 11, 2012
@jezdez
Django member
jezdez commented Jun 11, 2012

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 Jun 11, 2012
@idan
Django member
idan commented Jun 11, 2012

: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
Something went wrong with that request. Please try again.