10 December 2008

django-registration

This will be about (bad?) documentation.

Im in process of making small database inferface in django with few additional functions. I need to register people. This is the place where django-registration kicks in, I choose it to cut development time and to not reinvent the wheel.

Basic setup of django-registration is a breeze, but when it gets to template creation it gets worse. Information about context variables passed to the templates is hid among the rest of documentation. I found easier to dig it out from the code rather than from documentation. It could be so beautiful if it was included in overview.txt (in "Templates used by django-registration" section specifically).

I know that it is not much but it could be easy 5 minutes of setting up django-registration instead of 15 minutes poking with code and other documentation.

Fortunately I wont moan more but do something productive instead and produce better documentation ;) I know that in a week I will not remember which template takes which parameter and first place I'll be looking in is documentation. So here we go:

The views included in django-registration make use of five templates:

* ``registration/registration_form.html`` displays the registration
form for users to sign up. Gets ``form`` in template context. Default urlconf ``^register/``.

* ``registration/registration_complete.html`` is displayed after the
activation email has been sent, to tell the new user to check
his/her email. Does not get any context variables.

* ``registration/activation_email_subject.txt`` is used for the
subject of the activation email. Gets ``site`` which is site address as in Django sites. This template should render to only one line of text.

* ``registration/activation_email.txt`` is used for the body of the
activation email. Gets ``site``, ``expiration_days`` and ``activation_keys`` as context, ``expiration_days`` is ACCOUNT_ACTIVATION_DAYS value and ``activation_keys`` is activation key. Default urlconf for activation is: ``^activate/(?P\w+)/``.

* ``registration/activate.html`` is displayed when a user attempts to
activate his/her account. Gets ``account`` and ``expiration_days`` as context, ``account`` is False if activation failed and corresponding User object otherwise.

If I got everything right there is no need for more reading if one intends to get only basic registration. Hope this helps.

I reported it at http://www.bitbucket.org/ubernostrum/django-registration/issue/12/documentation-improvement

No comments: