<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>The Django admin documentation generator — Django 1.8.19 documentation</title>
<link rel="stylesheet" href="../../../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../../',
VERSION: '1.8.19',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../../../_static/jquery.js"></script>
<script type="text/javascript" src="../../../_static/underscore.js"></script>
<script type="text/javascript" src="../../../_static/doctools.js"></script>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="top" title="Django 1.8.19 documentation" href="../../../contents.html" />
<link rel="up" title="The Django admin site" href="index.html" />
<link rel="next" title="django.contrib.auth" href="../auth.html" />
<link rel="prev" title="Admin actions" href="actions.html" />
<script type="text/javascript" src="../../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../../templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body role="document">
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../../../index.html">Django 1.8.19 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../../../index.html">Home</a> |
<a title="Table of contents" href="../../../contents.html">Table of contents</a> |
<a title="Global index" href="../../../genindex.html">Index</a> |
<a title="Module index" href="../../../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="actions.html" title="Admin actions">previous</a>
|
<a href="../../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="../auth.html" title="<code class="docutils literal"><span class="pre">django.contrib.auth</span></code>">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="ref-contrib-admin-admindocs">
<div class="section" id="s-module-django.contrib.admindocs">
<span id="s-the-django-admin-documentation-generator"></span><span id="module-django.contrib.admindocs"></span><span id="the-django-admin-documentation-generator"></span><h1>The Django admin documentation generator<a class="headerlink" href="#module-django.contrib.admindocs" title="Permalink to this headline">¶</a></h1>
<p>Django’s <a class="reference internal" href="#module-django.contrib.admindocs" title="django.contrib.admindocs: Django's admin documentation generator."><code class="xref py py-mod docutils literal"><span class="pre">admindocs</span></code></a> app pulls documentation from the
docstrings of models, views, template tags, and template filters for any app in
<a class="reference internal" href="../../settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></code></a> and makes that documentation available from the
<a class="reference internal" href="index.html#module-django.contrib.admin" title="django.contrib.admin: Django's admin site."><code class="xref py py-mod docutils literal"><span class="pre">Django</span> <span class="pre">admin</span></code></a>.</p>
<p>You may, to some extent, utilize <a class="reference internal" href="#module-django.contrib.admindocs" title="django.contrib.admindocs: Django's admin documentation generator."><code class="xref py py-mod docutils literal"><span class="pre">admindocs</span></code></a> to quickly
document your own code. This has limited usage, however, as the app is
primarily intended for documenting templates, template tags, and filters.
For example, model methods that require arguments are purposefully omitted
from the documentation because they can’t be invoked from templates. The app
can still be useful since it doesn’t require you to write any extra
documentation (besides docstrings) and is conveniently available from the
<a class="reference internal" href="index.html#module-django.contrib.admin" title="django.contrib.admin: Django's admin site."><code class="xref py py-mod docutils literal"><span class="pre">Django</span> <span class="pre">admin</span></code></a>.</p>
<div class="section" id="s-overview">
<span id="overview"></span><h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<p>To activate the <a class="reference internal" href="#module-django.contrib.admindocs" title="django.contrib.admindocs: Django's admin documentation generator."><code class="xref py py-mod docutils literal"><span class="pre">admindocs</span></code></a>, you will need to do
the following:</p>
<ul class="simple">
<li>Add <a class="reference internal" href="#module-django.contrib.admindocs" title="django.contrib.admindocs: Django's admin documentation generator."><code class="xref py py-mod docutils literal"><span class="pre">django.contrib.admindocs</span></code></a> to your <a class="reference internal" href="../../settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></code></a>.</li>
<li>Add <code class="docutils literal"><span class="pre">url(r'^admin/doc/',</span> <span class="pre">include('django.contrib.admindocs.urls'))</span></code> to
your <code class="docutils literal"><span class="pre">urlpatterns</span></code>. Make sure it’s included <em>before</em> the
<code class="docutils literal"><span class="pre">r'^admin/'</span></code> entry, so that requests to <code class="docutils literal"><span class="pre">/admin/doc/</span></code> don’t get
handled by the latter entry.</li>
<li>Install the docutils Python module (<a class="reference external" href="http://docutils.sf.net/">http://docutils.sf.net/</a>).</li>
<li><strong>Optional:</strong> Using the admindocs bookmarklets requires
<code class="docutils literal"><span class="pre">django.contrib.admindocs.middleware.XViewMiddleware</span></code> to be installed.</li>
</ul>
<p>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.</p>
</div>
<div class="section" id="s-documentation-helpers">
<span id="documentation-helpers"></span><h2>Documentation helpers<a class="headerlink" href="#documentation-helpers" title="Permalink to this headline">¶</a></h2>
<p>The following special markup can be used in your docstrings to easily create
hyperlinks to other components:</p>
<table class="docutils">
<colgroup>
<col width="31%" />
<col width="69%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Django Component</th>
<th class="head">reStructuredText roles</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>Models</td>
<td><code class="docutils literal"><span class="pre">:model:`app_label.ModelName`</span></code></td>
</tr>
<tr class="row-odd"><td>Views</td>
<td><code class="docutils literal"><span class="pre">:view:`app_label.view_name`</span></code></td>
</tr>
<tr class="row-even"><td>Template tags</td>
<td><code class="docutils literal"><span class="pre">:tag:`tagname`</span></code></td>
</tr>
<tr class="row-odd"><td>Template filters</td>
<td><code class="docutils literal"><span class="pre">:filter:`filtername`</span></code></td>
</tr>
<tr class="row-even"><td>Templates</td>
<td><code class="docutils literal"><span class="pre">:template:`path/to/template.html`</span></code></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="s-model-reference">
<span id="model-reference"></span><h2>Model reference<a class="headerlink" href="#model-reference" title="Permalink to this headline">¶</a></h2>
<p>The <strong>models</strong> section of the <code class="docutils literal"><span class="pre">admindocs</span></code> page describes each model in the
system along with all the fields and methods (without any arguments) available
on it. While model properties don’t have any arguments, they are not listed.
Relationships to other models appear as hyperlinks. Descriptions are pulled
from <code class="docutils literal"><span class="pre">help_text</span></code> attributes on fields or from docstrings on model methods.</p>
<p>A model with useful documentation might look like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">BlogEntry</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Stores a single blog entry, related to :model:`blog.Blog` and</span>
<span class="sd"> :model:`auth.User`.</span>
<span class="sd"> """</span>
<span class="n">slug</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">SlugField</span><span class="p">(</span><span class="n">help_text</span><span class="o">=</span><span class="s2">"A short label, generally used in URLs."</span><span class="p">)</span>
<span class="n">author</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="n">User</span><span class="p">)</span>
<span class="n">blog</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="n">Blog</span><span class="p">)</span>
<span class="o">...</span>
<span class="k">def</span> <span class="nf">publish</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">"""Makes the blog entry live on the site."""</span>
<span class="o">...</span>
</pre></div>
</div>
</div>
<div class="section" id="s-view-reference">
<span id="view-reference"></span><h2>View reference<a class="headerlink" href="#view-reference" title="Permalink to this headline">¶</a></h2>
<p>Each URL in your site has a separate entry in the <code class="docutils literal"><span class="pre">admindocs</span></code> page, and
clicking on a given URL will show you the corresponding view. Helpful things
you can document in your view function docstrings include:</p>
<ul class="simple">
<li>A short description of what the view does.</li>
<li>The <strong>context</strong>, or a list of variables available in the view’s template.</li>
<li>The name of the template or templates that are used for that view.</li>
</ul>
<p>For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.shortcuts</span> <span class="k">import</span> <span class="n">render</span>
<span class="kn">from</span> <span class="nn">myapp.models</span> <span class="k">import</span> <span class="n">MyModel</span>
<span class="k">def</span> <span class="nf">my_view</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="n">slug</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Display an individual :model:`myapp.MyModel`.</span>
<span class="sd"> **Context**</span>
<span class="sd"> ``mymodel``</span>
<span class="sd"> An instance of :model:`myapp.MyModel`.</span>
<span class="sd"> **Template:**</span>
<span class="sd"> :template:`myapp/my_template.html`</span>
<span class="sd"> """</span>
<span class="n">context</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'mymodel'</span><span class="p">:</span> <span class="n">MyModel</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">slug</span><span class="o">=</span><span class="n">slug</span><span class="p">)}</span>
<span class="k">return</span> <span class="n">render</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="s1">'myapp/my_template.html'</span><span class="p">,</span> <span class="n">context</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="s-template-tags-and-filters-reference">
<span id="template-tags-and-filters-reference"></span><h2>Template tags and filters reference<a class="headerlink" href="#template-tags-and-filters-reference" title="Permalink to this headline">¶</a></h2>
<p>The <strong>tags</strong> and <strong>filters</strong> <code class="docutils literal"><span class="pre">admindocs</span></code> sections describe all the tags and
filters that come with Django (in fact, the <a class="reference internal" href="../../templates/builtins.html#ref-templates-builtins-tags"><span class="std std-ref">built-in tag reference</span></a> and <a class="reference internal" href="../../templates/builtins.html#ref-templates-builtins-filters"><span class="std std-ref">built-in filter reference</span></a> 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.</p>
</div>
<div class="section" id="s-template-reference">
<span id="template-reference"></span><h2>Template reference<a class="headerlink" href="#template-reference" title="Permalink to this headline">¶</a></h2>
<p>While <code class="docutils literal"><span class="pre">admindocs</span></code> does not include a place to document templates by
themselves, if you use the <code class="docutils literal"><span class="pre">:template:`path/to/template.html`</span></code> syntax in a
docstring the resulting page will verify the path of that template with
Django’s <a class="reference internal" href="../../templates/api.html#template-loaders"><span class="std std-ref">template loaders</span></a>. This can be a handy way to
check if the specified template exists and to show where on the filesystem that
template is stored.</p>
</div>
<div class="section" id="s-included-bookmarklets">
<span id="s-admindocs-bookmarklets"></span><span id="included-bookmarklets"></span><span id="admindocs-bookmarklets"></span><h2>Included Bookmarklets<a class="headerlink" href="#included-bookmarklets" title="Permalink to this headline">¶</a></h2>
<p>Several useful bookmarklets are available from the <code class="docutils literal"><span class="pre">admindocs</span></code> page:</p>
<dl class="docutils">
<dt>Documentation for this page</dt>
<dd>Jumps you from any page to the documentation for the view that generates
that page.</dd>
<dt>Show object ID</dt>
<dd>Shows the content-type and unique ID for pages that represent a single
object.</dd>
<dt>Edit this object</dt>
<dd>Jumps to the admin page for pages that represent a single object.</dd>
</dl>
<p>Using these bookmarklets requires that you are either logged into the
<a class="reference internal" href="index.html#module-django.contrib.admin" title="django.contrib.admin: Django's admin site."><code class="xref py py-mod docutils literal"><span class="pre">Django</span> <span class="pre">admin</span></code></a> as a
<a class="reference internal" href="../auth.html#django.contrib.auth.models.User" title="django.contrib.auth.models.User"><code class="xref py py-class docutils literal"><span class="pre">User</span></code></a> with
<a class="reference internal" href="../auth.html#django.contrib.auth.models.User.is_staff" title="django.contrib.auth.models.User.is_staff"><code class="xref py py-attr docutils literal"><span class="pre">is_staff</span></code></a> set to <code class="docutils literal"><span class="pre">True</span></code>, or that the
<code class="docutils literal"><span class="pre">XViewMiddleware</span></code> is installed and you are accessing the site from an IP
address listed in <a class="reference internal" href="../../settings.html#std:setting-INTERNAL_IPS"><code class="xref std std-setting docutils literal"><span class="pre">INTERNAL_IPS</span></code></a>.</p>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../../../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">The Django admin documentation generator</a><ul>
<li><a class="reference internal" href="#overview">Overview</a></li>
<li><a class="reference internal" href="#documentation-helpers">Documentation helpers</a></li>
<li><a class="reference internal" href="#model-reference">Model reference</a></li>
<li><a class="reference internal" href="#view-reference">View reference</a></li>
<li><a class="reference internal" href="#template-tags-and-filters-reference">Template tags and filters reference</a></li>
<li><a class="reference internal" href="#template-reference">Template reference</a></li>
<li><a class="reference internal" href="#included-bookmarklets">Included Bookmarklets</a></li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="actions.html">Admin actions</a></li>
<li>Next: <a href="../auth.html"><code class="docutils literal"><span class="pre">django.contrib.auth</span></code></a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../../../index.html">Django 1.8.19 documentation</a>
<ul><li><a href="../../index.html">API Reference</a>
<ul><li><a href="../index.html"><code class="docutils literal"><span class="pre">contrib</span></code> packages</a>
<ul><li><a href="index.html">The Django admin site</a>
<ul><li>The Django admin documentation generator</li></ul>
</li></ul></li></ul></li></ul>
</li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../../_sources/ref/contrib/admin/admindocs.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../../../search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Mar 10, 2018</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="actions.html" title="Admin actions">previous</a>
|
<a href="../../index.html" title="API Reference" accesskey="U">up</a>
|
<a href="../auth.html" title="<code class="docutils literal"><span class="pre">django.contrib.auth</span></code>">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
65530c6176058f9b54858c3b4f6385e6
>
files
>
701
