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.
You may, to some extent, utilize admindocs to quickly\ndocument your own code. This has limited usage, however, as the app is\nprimarily intended for documenting templates, template tags, and filters.\nFor example, model methods that require arguments are purposefully omitted\nfrom the documentation because they can’t be invoked from templates. The app\ncan still be useful since it doesn’t require you to write any extra\ndocumentation (besides docstrings) and is conveniently 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 (without any arguments) available\non it. While model properties don’t have any arguments, they are not listed.\nRelationships to other models appear as hyperlinks. Descriptions are pulled\nfrom help_text attributes 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 """\n slug = models.SlugField(help_text="A short label, generally used in URLs.")\n author = models.ForeignKey(User)\n blog = models.ForeignKey(Blog)\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 """\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.
Several useful bookmarklets are available from the admindocs page:
Jumps you from any page to the documentation for the view that generates\nthat page.
\nShows the content-type and unique ID for pages that represent a single\nobject.
\nJumps to the admin page for pages that represent a single object.
\nUsing these bookmarklets requires that you are either logged into the\nDjango admin as a\nUser with\nis_staff set to True, or that the\nXViewMiddleware is installed and you are accessing the site from an IP\naddress listed in INTERNAL_IPS.