More on admin documentation

November 12, 2007    Django

Since the last entry on admin documentation tricks seems to have been popular, and showed off a couple lesser-known things you can do, let’s take another look at the admin documentation system, and a couple more things you might not know about; in fact, until today I didn’t know about them, so if nothing else this entry will remind me that they exist and that I need to use them more.

Admin docs: a quick recap

In all Python programs, not just Django applications, you’re encouraged to provide documentation embedded directly in your code, via the use of docstrings. If you supply your modules, classes, methods and functions with docstrings, Python’s built-in help system (available by typing help() in the Python interpreter) will happily format and display them, and various useful tools exist which can scan large codebases and automatically extract the documentation if you’re into that sort of thing.

Django takes this a step further by making this documentation available in the admin interface; in the upper right-hand corner of each admin page is a link labeled “Documentation”, which will (if you have docutils installed) take you to an index of available documentation; from there you can browse through:

• Documentation for all of the template tags you have installed.
• Documentation for all of the template filters you have installed.
• Documentation for all the views which currently have URLs routed to them.
• Documentation for all the models you have installed, including lists of their fields, methods and relationships.

This is all pretty handy, and it’s generally a very good idea to supply docstrings for all of your code so that this and other documentation systems can display useful information to users of your code. Django also uses docutils to run reStructuredText conversion on your docstrings, which makes it easy to generate friendly, well-formatted HTML.

Useful reST tricks

Because reStructuredText is extremely flexible and extensible, Django enables a few special-purpose tricks in the formatting it allows, which you can take advantage of to not only provide documentation, but provide cross-referenced documentation. It works by using a special label in front of certain parts of the documentation; for example, if you’re documenting a view which shows a single entry from a weblog application, you could do something like the following:

def entry_detail(request, year, month, day, slug):
    """
    Detail view of a :model:`blog.Entry`, performing a lookup based on the
    publication date of the ``Entry`` and its slug.
    
    """

In the admin documentation for this view, the text “blog.Entry” will become a link to the documentation for the Entry model in the blog application. This also works for linking to views:

def entry_detail(request, year, month, day, slug):
    """
    Detail view of a :model:`blog.Entry`.
    
    This is a short wrapper around the :view:`django.views.generic.date_based.object_detail`
    generic view.
    
    """

And lo and behold, you’ll get a link to the documentation for the date-based object_detail view. Django recognizes five of these special labels and will generate links from them accordingly:

• :model: links to model documentation, and takes the app label and model name (which we’ve already looked at, and which, as you might be noticing, get used all over the place inside Django) of the model to link to.
• :view: links to view documentation, and takes the dotted Python path to the view.
• :tag: links to documentation for a template tag, and takes the name of the tag.
• :filter: links to documentation for a template filter, and takes the name of the filter.
• :template: links to documentation for a template, and takes the name of the template.

Documentation for templates

This one threw me for a bit of a loop today when I saw it used for the first time, because it’s not exposed as prominently as the other documentation areas (and with good reason: right now Django doesn’t have any automatiac way of building up lists of templates the way it can build up lists of models, views, tags and filters). Django’s template documentation doesn’t actually describe the template’s contents — that’s the job of the view documentation, which should list the context it supplies — but it does perform one incredibly useful function: given the path to a template name, minus the file extension (which is how, prior to Django’s 0.95 release, template names used to be specified), it will display a page which:

1. Looks at your ADMIN_FOR setting, which must be set for this to work, and from it gets a list of all the settings modules in use on sites being administred by this instance of the admin interface.
2. Builds up a list of all of the directories used for templates, by scanning the TEMPLATE_DIRS setting inside each of those settings modules.
3. Appends “.html” to the template name and starts looking in every one of the template directories to see if it finds the template.

The end result is a page which displays all of your template directories (as specified in TEMPLATE_DIRS; application directories and other specialized loaders aren’t considered), in the order in which Django will look inside them, and next to each one displays a note if the specified template name could not be found in that directory.

What this boils down to is a way to see whether you have a template that one of your views requires, and to find out which template directory it will be loaded out of (which is a lifesaver when you have multiple template directories and aren’t quite sure which version of a template is being used).

And, as mentiond above, you can use the special :template: label in your docstrings to provide a link directly to this documentation; for example:

def entry_detail(request, year, month, day, slug):
    """
    Detail view of a :model:`blog.Entry`.
    
    Uses the template :template:`blog/entry_detail`.
    
    """

From the documentation page for that view, you could click the link for the template, and immediately see whether you have that template and which directory it will be found in first.

Go forth and document

Thoroughly documenting your applications is already a good idea, and fits in neatly with Python’s general wisdom of noting that code is read far more often than it’s written, and Django’s admin documentation system (which will become its own standalone application once newforms-admin is finished) provides an easy way to expose your documentation over the web to administrators of your Django-powered sites. And, as we’ve seen repeatedly, good documentation also lets Django provide powerful aids to debugging, by letting you see exactly which view a URL routes to, which object a view is retrieving, whether a given template exists in your template directories and — through properly cross-referenced documentation — how your entire application fits together to form a cohesive whole.

So the next time you’re working on a Django application, remember these tricks and put in the extra time to provide quality documentation along with your code; a few months down the road, when somebody (maybe even you) has to figure out how it works and possibly how to maintain it, you’ll be glad you did.