# Django 1.8.18.dev20170123152445 documentation

# The Django admin documentation generator

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`.

You may, to some extent, utilize `admindocs` to quickly document your own code. This has limited usage, however, as the app is primarily intended for documenting templates, template tags, and filters. For example, model methods that require arguments are purposefully omitted from the documentation because they can’t be invoked from templates. The app can still be useful since it doesn’t require you to write any extra documentation (besides docstrings) and is conveniently available from the `Django admin`.

## Overview

To activate the `admindocs`, you will need to do the following:

- Add `django.contrib.admindocs` to your `INSTALLED_APPS`.
- Add `url(r'^admin/doc/', include('django.contrib.admindocs.urls'))` to your `urlpatterns`. Make sure it’s included before the `r'^admin/'` entry, so that requests to `/admin/doc/` don’t get handled by the latter entry.
- Install the docutils Python module (http://docutils.sf.net/).
- Optional: Using the admindocs bookmarklets requires `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.

## Documentation helpers

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``

## Model reference

The models section of the `admindocs` page describes each model in the system along with all the fields and methods (without any arguments) available on it. While model properties don’t have any arguments, they are not listed. 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."""
            ...

## View reference

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:

- 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:

    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)

## Template tags and filters reference

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.

## Template reference

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.

## Included Bookmarklets

Several useful bookmarklets are available from the `admindocs` page:

Documentation for this page
  Jumps you from any page to the documentation for the view that generates that page.
Show object ID
  Shows the content-type and unique ID for pages that represent a single object.
Edit this object
  Jumps to the admin page for pages that represent a single object.

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 `XViewMiddleware` is installed and you are accessing the site from an IP address listed in `INTERNAL_IPS`.