151 lines
5.2 KiB
Plaintext
151 lines
5.2 KiB
Plaintext
========================================
|
|
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 docutils Python module (https://docutils.sourceforge.io/).
|
|
* **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.
|
|
|
|
.. versionchanged:: 4.0
|
|
|
|
Older versions don't display model cached properties.
|
|
|
|
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``.
|