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
.
To activate the admindocs
, you will need to do
the following:
django.contrib.admindocs
to your INSTALLED_APPS
.path('admin/doc/', include('django.contrib.admindocs.urls'))
to
your urlpatterns
. Make sure it’s included before the
'admin/'
entry, so that requests to /admin/doc/
don’t get
handled by the latter entry.django.contrib.admindocs.middleware.XViewMiddleware
to be installed.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:`app_label.ModelName` |
Views | :view:`app_label.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,
models.SET_NULL,
blank=True, null=True,
)
blog = models.ForeignKey(Blog, models.CASCADE)
...
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 django.shortcuts import render
from myapp.models import MyModel
def my_view(request, slug):
"""
Display an individual :model:`myapp.MyModel`.
**Context**
``mymodel``
An instance of :model:`myapp.MyModel`.
**Template:**
:template:`myapp/my_template.html`
"""
context = {'mymodel': MyModel.objects.get(slug=slug)}
return render(request, 'myapp/my_template.html', context)
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.
One bookmarklet is available from the admindocs
page:
Using this bookmarklet requires that XViewMiddleware
is installed and that
you are logged into the Django admin
as a
User
with
is_staff
set to True
.
Dec 24, 2018