| 1 |
======================================== |
| 2 |
The Django admin documentation generator |
| 3 |
======================================== |
| 4 |
|
| 5 |
.. module:: django.contrib.admindocs |
| 6 |
:synopsis: Django's admin documentation generator. |
| 7 |
|
| 8 |
.. currentmodule:: django.contrib.admindocs |
| 9 |
|
| 10 |
Django's :mod:`~django.contrib.admindocs` app pulls documentation from the |
| 11 |
docstrings of models, views, template tags, and template filters for any app in |
| 12 |
:setting:`INSTALLED_APPS` and makes that documentation available from the |
| 13 |
:mod:`Django admin <django.contrib.admin>`. |
| 14 |
|
| 15 |
Overview |
| 16 |
======== |
| 17 |
|
| 18 |
To activate the :mod:`~django.contrib.admindocs`, you will need to do |
| 19 |
the following: |
| 20 |
|
| 21 |
* Add :mod:`django.contrib.admindocs` to your :setting:`INSTALLED_APPS`. |
| 22 |
* Add ``path('admin/doc/', include('django.contrib.admindocs.urls'))`` to |
| 23 |
your ``urlpatterns``. Make sure it's included *before* the |
| 24 |
``'admin/'`` entry, so that requests to ``/admin/doc/`` don't get |
| 25 |
handled by the latter entry. |
| 26 |
* Install the :pypi:`docutils` 0.19+ package. |
| 27 |
* **Optional:** Using the admindocs bookmarklets requires |
| 28 |
``django.contrib.admindocs.middleware.XViewMiddleware`` to be installed. |
| 29 |
|
| 30 |
Once those steps are complete, you can start browsing the documentation by |
| 31 |
going to your admin interface and clicking the "Documentation" link in the |
| 32 |
upper right of the page. |
| 33 |
|
| 34 |
.. _admindocs-helpers: |
| 35 |
|
| 36 |
Documentation helpers |
| 37 |
===================== |
| 38 |
|
| 39 |
The following special markup can be used in your docstrings to easily create |
| 40 |
hyperlinks to other components: |
| 41 |
|
| 42 |
================= ======================= |
| 43 |
Django Component reStructuredText roles |
| 44 |
================= ======================= |
| 45 |
Models ``:model:`app_label.ModelName``` |
| 46 |
Views ``:view:`app_label.view_name``` |
| 47 |
Template tags ``:tag:`tagname``` |
| 48 |
Template filters ``:filter:`filtername``` |
| 49 |
Templates ``:template:`path/to/template.html``` |
| 50 |
================= ======================= |
| 51 |
|
| 52 |
Each of these support custom link text with the format |
| 53 |
``:role:`link text <link>```. For example, ``:tag:`block <built_in-block>```. |
| 54 |
|
| 55 |
.. versionchanged:: 5.2 |
| 56 |
|
| 57 |
Support for custom link text was added. |
| 58 |
|
| 59 |
.. _admindocs-model-reference: |
| 60 |
|
| 61 |
Model reference |
| 62 |
=============== |
| 63 |
|
| 64 |
The **models** section of the ``admindocs`` page describes each model that the |
| 65 |
user has access to along with all the fields, properties, and methods available |
| 66 |
on it. Relationships to other models appear as hyperlinks. Descriptions are |
| 67 |
pulled from ``help_text`` attributes on fields or from docstrings on model |
| 68 |
methods. |
| 69 |
|
| 70 |
A model with useful documentation might look like this:: |
| 71 |
|
| 72 |
class BlogEntry(models.Model): |
| 73 |
""" |
| 74 |
Stores a single blog entry, related to :model:`blog.Blog` and |
| 75 |
:model:`auth.User`. |
| 76 |
""" |
| 77 |
|
| 78 |
slug = models.SlugField(help_text="A short label, generally used in URLs.") |
| 79 |
author = models.ForeignKey( |
| 80 |
User, |
| 81 |
models.SET_NULL, |
| 82 |
blank=True, |
| 83 |
null=True, |
| 84 |
) |
| 85 |
blog = models.ForeignKey(Blog, models.CASCADE) |
| 86 |
... |
| 87 |
|
| 88 |
def publish(self): |
| 89 |
"""Makes the blog entry live on the site.""" |
| 90 |
... |
| 91 |
|
| 92 |
.. versionchanged:: 5.2 |
| 93 |
|
| 94 |
Access was restricted to only allow users with model view or change |
| 95 |
permissions. |
| 96 |
|
| 97 |
View reference |
| 98 |
============== |
| 99 |
|
| 100 |
Each URL in your site has a separate entry in the ``admindocs`` page, and |
| 101 |
clicking on a given URL will show you the corresponding view. Helpful things |
| 102 |
you can document in your view function docstrings include: |
| 103 |
|
| 104 |
* A short description of what the view does. |
| 105 |
* The **context**, or a list of variables available in the view's template. |
| 106 |
* The name of the template or templates that are used for that view. |
| 107 |
|
| 108 |
For example:: |
| 109 |
|
| 110 |
from django.shortcuts import render |
| 111 |
|
| 112 |
from myapp.models import MyModel |
| 113 |
|
| 114 |
|
| 115 |
def my_view(request, slug): |
| 116 |
""" |
| 117 |
Display an individual :model:`myapp.MyModel`. |
| 118 |
|
| 119 |
**Context** |
| 120 |
|
| 121 |
``mymodel`` |
| 122 |
An instance of :model:`myapp.MyModel`. |
| 123 |
|
| 124 |
**Template:** |
| 125 |
|
| 126 |
:template:`myapp/my_template.html` |
| 127 |
""" |
| 128 |
context = {"mymodel": MyModel.objects.get(slug=slug)} |
| 129 |
return render(request, "myapp/my_template.html", context) |
| 130 |
|
| 131 |
Template tags and filters reference |
| 132 |
=================================== |
| 133 |
|
| 134 |
The **tags** and **filters** ``admindocs`` sections describe all the tags and |
| 135 |
filters that come with Django (in fact, the :ref:`built-in tag reference |
| 136 |
<ref-templates-builtins-tags>` and :ref:`built-in filter reference |
| 137 |
<ref-templates-builtins-filters>` documentation come directly from those |
| 138 |
pages). Any tags or filters that you create or are added by a third-party app |
| 139 |
will show up in these sections as well. |
| 140 |
|
| 141 |
|
| 142 |
Template reference |
| 143 |
================== |
| 144 |
|
| 145 |
While ``admindocs`` does not include a place to document templates by |
| 146 |
themselves, if you use the ``:template:`path/to/template.html``` syntax in a |
| 147 |
docstring the resulting page will verify the path of that template with |
| 148 |
Django's :ref:`template loaders <template-loaders>`. This can be a handy way to |
| 149 |
check if the specified template exists and to show where on the filesystem that |
| 150 |
template is stored. |
| 151 |
|
| 152 |
.. _admindocs-bookmarklets: |
| 153 |
|
| 154 |
Included Bookmarklets |
| 155 |
===================== |
| 156 |
|
| 157 |
One bookmarklet is available from the ``admindocs`` page: |
| 158 |
|
| 159 |
Documentation for this page |
| 160 |
Jumps you from any page to the documentation for the view that generates |
| 161 |
that page. |
| 162 |
|
| 163 |
Using this bookmarklet requires that ``XViewMiddleware`` is installed and that |
| 164 |
you are logged into the :mod:`Django admin <django.contrib.admin>` as a |
| 165 |
:class:`~django.contrib.auth.models.User` with |
| 166 |
:attr:`~django.contrib.auth.models.User.is_staff` set to ``True``. |