1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
========================================
The Django admin documentation generator
========================================
.. module:: django.contrib.admindocs
:synopsis: Django's admin documentation generator.
.. currentmodule:: django.contrib.admindocs
Django's :mod:`~django.contrib.admindocs` app pulls documentation from the
docstrings of models, views, template tags, and template filters for any app in
:setting:`INSTALLED_APPS` and makes that documentation available from the
:mod:`Django admin <django.contrib.admin>`.
Overview
========
To activate the :mod:`~django.contrib.admindocs`, you will need to do
the following:
* Add :mod:`django.contrib.admindocs` to your :setting:`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 :pypi:`docutils` package.
* **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, properties, 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 :ref:`built-in tag reference
<ref-templates-builtins-tags>` and :ref:`built-in filter reference
<ref-templates-builtins-filters>` 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 :ref:`template loaders <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.
.. _admindocs-bookmarklets:
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 :mod:`Django admin <django.contrib.admin>` as a
:class:`~django.contrib.auth.models.User` with
:attr:`~django.contrib.auth.models.User.is_staff` set to ``True``.
|
