<!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"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>The Django admin documentation generator — Django 1.5.9 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.5.9', 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="top" title="Django 1.5.9 documentation" href="../../../index.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> <div class="document"> <div id="custom-doc" class="yui-t6"> <div id="hd"> <h1><a href="../../../index.html">Django 1.5.9 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="<tt class="docutils literal"><span class="pre">django.contrib.auth</span></tt>">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."><tt class="xref py py-mod docutils literal"><span class="pre">admindocs</span></tt></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"><tt class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></tt></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."><tt class="xref py py-mod docutils literal"><span class="pre">Django</span> <span class="pre">admin</span></tt></a>.</p> <p>In addition to providing offline documentation for all template tags and template filters that ship with Django, you may utilize admindocs to quickly document your own code.</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."><tt class="xref py py-mod docutils literal"><span class="pre">admindocs</span></tt></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."><tt class="xref py py-mod docutils literal"><span class="pre">django.contrib.admindocs</span></tt></a> to your <a class="reference internal" href="../../settings.html#std:setting-INSTALLED_APPS"><tt class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></tt></a>.</li> <li>Add <tt class="docutils literal"><span class="pre">(r'^admin/doc/',</span> <span class="pre">include('django.contrib.admindocs.urls'))</span></tt> to your <tt class="docutils literal"><span class="pre">urlpatterns</span></tt>. Make sure it’s included <em>before</em> the <tt class="docutils literal"><span class="pre">r'^admin/'</span></tt> entry, so that requests to <tt class="docutils literal"><span class="pre">/admin/doc/</span></tt> 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> Linking to templates requires the <a class="reference internal" href="../../settings.html#std:setting-ADMIN_FOR"><tt class="xref std std-setting docutils literal"><span class="pre">ADMIN_FOR</span></tt></a> setting to be configured.</li> <li><strong>Optional:</strong> Using the admindocs bookmarklets requires the <a class="reference internal" href="../../middleware.html#module-django.middleware.doc" title="django.middleware.doc: Middleware to help your app self-document."><tt class="xref py py-mod docutils literal"><span class="pre">XViewMiddleware</span></tt></a> 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><tt class="docutils literal"><span class="pre">:model:`appname.ModelName`</span></tt></td> </tr> <tr class="row-odd"><td>Views</td> <td><tt class="docutils literal"><span class="pre">:view:`appname.view_name`</span></tt></td> </tr> <tr class="row-even"><td>Template tags</td> <td><tt class="docutils literal"><span class="pre">:tag:`tagname`</span></tt></td> </tr> <tr class="row-odd"><td>Template filters</td> <td><tt class="docutils literal"><span class="pre">:filter:`filtername`</span></tt></td> </tr> <tr class="row-even"><td>Templates</td> <td><tt class="docutils literal"><span class="pre">:template:`path/to/template.html`</span></tt></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 <tt class="docutils literal"><span class="pre">admindocs</span></tt> 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 <tt class="docutils literal"><span class="pre">help_text</span></tt> attributes on fields or from docstrings on model methods.</p> <p>A model with useful documentation might look like this:</p> <div class="highlight-python"><div class="highlight"><pre><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="s">"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 <tt class="docutils literal"><span class="pre">admindocs</span></tt> 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-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">myapp.models</span> <span class="kn">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"> ``RequestContext``</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="k">return</span> <span class="n">render_to_response</span><span class="p">(</span><span class="s">'myapp/my_template.html'</span><span class="p">,</span> <span class="p">{</span> <span class="s">'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="p">},</span> <span class="n">context_instance</span><span class="o">=</span><span class="n">RequestContext</span><span class="p">(</span><span class="n">request</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> <tt class="docutils literal"><span class="pre">admindocs</span></tt> 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"><em>built-in tag reference</em></a> and <a class="reference internal" href="../../templates/builtins.html#ref-templates-builtins-filters"><em>built-in filter reference</em></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 <tt class="docutils literal"><span class="pre">admindocs</span></tt> does not include a place to document templates by themselves, if you use the <tt class="docutils literal"><span class="pre">:template:`path/to/template.html`</span></tt> 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"><em>template loaders</em></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="included-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 <tt class="docutils literal"><span class="pre">admindocs</span></tt> 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."><tt class="xref py py-mod docutils literal"><span class="pre">Django</span> <span class="pre">admin</span></tt></a> as a <a class="reference internal" href="../auth.html#django.contrib.auth.models.User" title="django.contrib.auth.models.User"><tt class="xref py py-class docutils literal"><span class="pre">User</span></tt></a> with <a class="reference internal" href="../auth.html#django.contrib.auth.models.User.is_staff" title="django.contrib.auth.models.User.is_staff"><tt class="xref py py-attr docutils literal"><span class="pre">is_staff</span></tt></a> set to <cite>True</cite>, or that the <a class="reference internal" href="../../middleware.html#module-django.middleware.doc" title="django.middleware.doc: Middleware to help your app self-document."><tt class="xref py py-mod docutils literal"><span class="pre">django.middleware.doc</span></tt></a> middleware and <a class="reference internal" href="../../middleware.html#module-django.middleware.doc" title="django.middleware.doc: Middleware to help your app self-document."><tt class="xref py py-mod docutils literal"><span class="pre">XViewMiddleware</span></tt></a> are installed and you are accessing the site from an IP address listed in <a class="reference internal" href="../../settings.html#std:setting-INTERNAL_IPS"><tt class="xref std std-setting docutils literal"><span class="pre">INTERNAL_IPS</span></tt></a>.</p> </div> </div> </div> </div> </div> <div class="yui-b" id="sidebar"> <div class="sphinxsidebar"> <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"><tt class="docutils literal"><span class="pre">django.contrib.auth</span></tt></a></li> </ul> <h3>You are here:</h3> <ul> <li> <a href="../../../index.html">Django 1.5.9 documentation</a> <ul><li><a href="../../index.html">API Reference</a> <ul><li><a href="../index.html"><tt class="docutils literal"><span class="pre">contrib</span></tt> 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> <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 id="searchbox" style="display: none"> <h3>Quick search</h3> <form class="search" action="../../../search.html" method="get"> <input type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <h3>Last update:</h3> <p class="topless">Aug 21, 2014</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="<tt class="docutils literal"><span class="pre">django.contrib.auth</span></tt>">next</a> »</div> </div> </div> <div class="clearer"></div> </div> </body> </html>