# Django 2.1.8.dev20190330215650 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`.

## Overview

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

- Add `django.contrib.admindocs` to your `INSTALLED_APPS`.
- Add `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.
- 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 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."""
            ...

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

One bookmarklet is available from the `admindocs` page:

Documentation for this page
  Jumps you from any page to the documentation for the view that generates that 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`.