Django's admindocs app pulls documentation from the\ndocstrings of models, views, template tags, and template filters for any app in\nINSTALLED_APPS and makes that documentation available from the\nDjango admin.
To activate the admindocs, you will need to do\nthe following:
Add django.contrib.admindocs to your INSTALLED_APPS.
Add url(r'^admin/doc/', include('django.contrib.admindocs.urls')) to\nyour urlpatterns. Make sure it's included before the\nr'^admin/' entry, so that requests to /admin/doc/ don't get\nhandled by the latter entry.
Install the docutils Python module (http://docutils.sf.net/).
Optional: Using the admindocs bookmarklets requires\ndjango.contrib.admindocs.middleware.XViewMiddleware to be installed.
Once those steps are complete, you can start browsing the documentation by\ngoing to your admin interface and clicking the "Documentation" link in the\nupper right of the page.
\nThe following special markup can be used in your docstrings to easily create\nhyperlinks to other components:
\nDjango Component | \nreStructuredText roles | \n
|---|---|
Models | \n
| \n
Views | \n
| \n
Template tags | \n
| \n
Template filters | \n
| \n
Templates | \n
| \n
The models section of the admindocs page describes each model in the\nsystem along with all the fields and methods available on it. Relationships\nto other models appear as hyperlinks. Descriptions are pulled from help_text\nattributes on fields or from docstrings on model methods.
A model with useful documentation might look like this:
\nclass BlogEntry(models.Model):\n """\n Stores a single blog entry, related to :model:`blog.Blog` and\n :model:`auth.User`.\n """\n slug = models.SlugField(help_text="A short label, generally used in URLs.")\n author = models.ForeignKey(\n User,\n models.SET_NULL,\n blank=True, null=True,\n )\n blog = models.ForeignKey(Blog, models.CASCADE)\n ...\n\n def publish(self):\n """Makes the blog entry live on the site."""\n ...\nEach URL in your site has a separate entry in the admindocs page, and\nclicking on a given URL will show you the corresponding view. Helpful things\nyou can document in your view function docstrings include:
A short description of what the view does.
The context, or a list of variables available in the view's template.
The name of the template or templates that are used for that view.
For example:
\nfrom django.shortcuts import render\n\nfrom myapp.models import MyModel\n\ndef my_view(request, slug):\n """\n Display an individual :model:`myapp.MyModel`.\n\n **Context**\n\n ``mymodel``\n An instance of :model:`myapp.MyModel`.\n\n **Template:**\n\n :template:`myapp/my_template.html`\n """\n context = {'mymodel': MyModel.objects.get(slug=slug)}\n return render(request, 'myapp/my_template.html', context)\nWhile admindocs does not include a place to document templates by\nthemselves, if you use the :template:`path/to/template.html` syntax in a\ndocstring the resulting page will verify the path of that template with\nDjango's template loaders. This can be a handy way to\ncheck if the specified template exists and to show where on the filesystem that\ntemplate is stored.
One bookmarklet is available from the admindocs page:
Jumps you from any page to the documentation for the view that generates\nthat page.
\nUsing this bookmarklet requires that XViewMiddleware is installed and that\nyou are logged into the Django admin as a\nUser with\nis_staff set to True.