Debian Codegraph @

docs/ref/contrib/admin/admindocs.txt

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