Django’s admindocs app pulls documentation from the docstrings of models, views, template tags, and template filters for any app in INSTALLED_APPS and makes that documentation available from the Django admin.
In addition to providing offline documentation for all template tags and template filters that ship with Django, you may utilize admindocs to quickly document your own code.
To activate the admindocs, you will need to do the following:
Once those steps are complete, you can start browsing the documentation by going to your admin interface and clicking the “Documentation” link in the upper right of the page.
The following special markup can be used in your docstrings to easily create hyperlinks to other components:
Django Component | reStructuredText roles |
---|---|
Models | :model:`appname.ModelName` |
Views | :view:`appname.view_name` |
Template tags | :tag:`tagname` |
Template filters | :filter:`filtername` |
Templates | :template:`path/to/template.html` |
The models section of the admindocs page describes each model in the system along with all the fields and methods available on it. Relationships to other models appear as hyperlinks. Descriptions are pulled from help_text attributes on fields or from docstrings on model methods.
A model with useful documentation might look like this:
class BlogEntry(models.Model):
"""
Stores a single blog entry, related to :model:`blog.Blog` and
:model:`auth.User`.
"""
slug = models.SlugField(help_text="A short label, generally used in URLs.")
author = models.ForeignKey(User)
blog = models.ForeignKey(Blog)
...
def publish(self):
"""Makes the blog entry live on the site."""
...
Each URL in your site has a separate entry in the admindocs page, and clicking on a given URL will show you the corresponding view. Helpful things you can document in your view function docstrings include:
For example:
from myapp.models import MyModel
def my_view(request, slug):
"""
Display an individual :model:`myapp.MyModel`.
**Context**
``RequestContext``
``mymodel``
An instance of :model:`myapp.MyModel`.
**Template:**
:template:`myapp/my_template.html`
"""
return render_to_response('myapp/my_template.html', {
'mymodel': MyModel.objects.get(slug=slug)
}, context_instance=RequestContext(request))
The tags and filters admindocs sections describe all the tags and filters that come with Django (in fact, the built-in tag reference and built-in filter reference documentation come directly from those pages). Any tags or filters that you create or are added by a third-party app will show up in these sections as well.
While admindocs does not include a place to document templates by themselves, if you use the :template:`path/to/template.html` syntax in a docstring the resulting page will verify the path of that template with Django’s template loaders. This can be a handy way to check if the specified template exists and to show where on the filesystem that template is stored.
Several useful bookmarklets are available from the admindocs page:
Using these bookmarklets requires that you are either logged into the Django admin as a User with is_staff set to True, or that the django.middleware.doc middleware and XViewMiddleware are installed and you are accessing the site from an IP address listed in INTERNAL_IPS.
Dec 23, 2012