<!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>How the Django documentation works — Django v1.2 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.2',
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 v1.2 documentation" href="../index.html" />
<link rel="up" title="Django internals" href="index.html" />
<link rel="next" title="Django committers" href="committers.html" />
<link rel="prev" title="Contributing to Django" href="contributing.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 = "../ref/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 v1.2 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="contributing.html" title="Contributing to Django">previous</a>
|
<a href="index.html" title="Django internals" accesskey="U">up</a>
|
<a href="committers.html" title="Django committers">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="internals-documentation">
<div class="section" id="s-how-the-django-documentation-works">
<span id="how-the-django-documentation-works"></span><h1>How the Django documentation works<a class="headerlink" href="#how-the-django-documentation-works" title="Permalink to this headline">¶</a></h1>
<p>... and how to contribute.</p>
<p>Django’s documentation uses the <a class="reference external" href="http://sphinx.pocoo.org/">Sphinx</a> documentation system, which in turn is
based on <a class="reference external" href="http://docutils.sourceforge.net/">docutils</a>. The basic idea is that lightly-formatted plain-text
documentation is transformed into HTML, PDF, and any other output format.</p>
<p>To actually build the documentation locally, you’ll currently need to install
Sphinx – <tt class="docutils literal"><span class="pre">easy_install</span> <span class="pre">Sphinx</span></tt> should do the trick.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The Django documentation can be generated with Sphinx version 0.6 or
newer, but we recommend using Sphinx 1.0.2 or newer.</p>
</div>
<p>Then, building the HTML is easy; just <tt class="docutils literal"><span class="pre">make</span> <span class="pre">html</span></tt> from the <tt class="docutils literal"><span class="pre">docs</span></tt> directory.</p>
<p>To get started contributing, you’ll want to read the <a class="reference external" href="http://sphinx.pocoo.org/rest.html">reStructuredText
Primer</a>. After that, you’ll want to read about the <a class="reference external" href="http://sphinx.pocoo.org/markup/">Sphinx-specific markup</a>
that’s used to manage metadata, indexing, and cross-references.</p>
<p>The main thing to keep in mind as you write and edit docs is that the more
semantic markup you can add the better. So:</p>
<div class="highlight-python"><pre>Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...</pre>
</div>
<p>Isn't nearly as helpful as:</p>
<div class="highlight-python"><pre>Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...</pre>
</div>
<p>This is because Sphinx will generate proper links for the latter, which greatly
helps readers. There's basically no limit to the amount of useful markup you can
add.</p>
<div class="section" id="s-django-specific-markup">
<span id="django-specific-markup"></span><h2>Django-specific markup<a class="headerlink" href="#django-specific-markup" title="Permalink to this headline">¶</a></h2>
<p>Besides the <a class="reference external" href="http://sphinx.pocoo.org/markup/desc.html">Sphinx built-in markup</a>, Django's docs defines some extra description units:</p>
<ul>
<li><p class="first">Settings:</p>
<div class="highlight-python"><pre>.. setting:: INSTALLED_APPS</pre>
</div>
<p>To link to a setting, use <tt class="docutils literal"><span class="pre">:setting:`INSTALLED_APPS`</span></tt>.</p>
</li>
<li><p class="first">Template tags:</p>
<div class="highlight-python"><pre>.. templatetag:: regroup</pre>
</div>
<p>To link, use <tt class="docutils literal"><span class="pre">:ttag:`regroup`</span></tt>.</p>
</li>
<li><p class="first">Template filters:</p>
<div class="highlight-python"><pre>.. templatefilter:: linebreaksbr</pre>
</div>
<p>To link, use <tt class="docutils literal"><span class="pre">:tfilter:`linebreaksbr`</span></tt>.</p>
</li>
<li><p class="first">Field lookups (i.e. <tt class="docutils literal"><span class="pre">Foo.objects.filter(bar__exact=whatever)</span></tt>):</p>
<div class="highlight-python"><pre>.. fieldlookup:: exact</pre>
</div>
<p>To link, use <tt class="docutils literal"><span class="pre">:lookup:`exact`</span></tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">django-admin</span></tt> commands:</p>
<div class="highlight-python"><pre>.. django-admin:: syncdb</pre>
</div>
<p>To link, use <tt class="docutils literal"><span class="pre">:djadmin:`syncdb`</span></tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">django-admin</span></tt> command-line options:</p>
<div class="highlight-python"><pre>.. django-admin-option:: --traceback</pre>
</div>
<p>To link, use <tt class="docutils literal"><span class="pre">:djadminopt:`--traceback`</span></tt>.</p>
</li>
</ul>
</div>
<div class="section" id="s-an-example">
<span id="an-example"></span><h2>An example<a class="headerlink" href="#an-example" title="Permalink to this headline">¶</a></h2>
<p>For a quick example of how it all fits together, consider this hypothetical
example:</p>
<ul>
<li><p class="first">First, the <tt class="docutils literal"><span class="pre">ref/settings.txt</span></tt> document could have an overall layout
like this:</p>
<div class="highlight-rst"><div class="highlight"><pre><span class="gh">========</span>
<span class="gh">Settings</span>
<span class="gh">========</span>
<span class="cp">...</span>
<span class="cp">.. _available-settings:</span>
<span class="gh">Available settings</span>
<span class="gh">==================</span>
<span class="cp">...</span>
<span class="cp">.. _deprecated-settings:</span>
<span class="gh">Deprecated settings</span>
<span class="gh">===================</span>
<span class="cp">...</span>
</pre></div>
</div>
</li>
<li><p class="first">Next, the <tt class="docutils literal"><span class="pre">topics/settings.txt</span></tt> document could contain something like
this:</p>
<div class="highlight-rst"><div class="highlight"><pre>You can access a :ref:`listing of all available settings
<span class="nt"><available-settings></span>`. For a list of deprecated settings see
<span class="na">:ref:</span><span class="nv">`deprecated-settings`</span>.
You can find both in the <span class="na">:doc:</span><span class="nv">`settings reference document </ref/settings>`</span>.
</pre></div>
</div>
<p>We use the Sphinx <a class="reference external" href="http://sphinx.pocoo.org/markup/inline.html#role-doc">doc</a> cross reference element when we want to link to
another document as a whole and the <a class="reference external" href="http://sphinx.pocoo.org/markup/inline.html#role-ref">ref</a> element when we want to link to
an arbitrary location in a document.</p>
</li>
</ul>
<ul>
<li><p class="first">Next, notice how the settings are annotated:</p>
<div class="highlight-rst"><div class="highlight"><pre><span class="p">..</span> <span class="ow">setting</span><span class="p">::</span> ADMIN_FOR
<span class="gh">ADMIN_FOR</span>
<span class="gh">---------</span>
Default: <span class="s">``()``</span> (Empty tuple)
Used for admin-site settings modules, this should be a tuple of settings
modules (in the format <span class="s">``'foo.bar.baz'``</span>) for which this site is an
admin.
The admin site uses this in its automatically-introspected
documentation of models, views and template tags.
</pre></div>
</div>
<p>This marks up the following header as the "canonical" target for the
setting <tt class="docutils literal"><span class="pre">ADMIN_FOR</span></tt> This means any time I talk about <tt class="docutils literal"><span class="pre">ADMIN_FOR</span></tt>, I
can reference it using <tt class="docutils literal"><span class="pre">:setting:`ADMIN_FOR`</span></tt>.</p>
</li>
</ul>
<p>That's basically how everything fits together.</p>
</div>
<div class="section" id="s-todo">
<span id="todo"></span><h2>TODO<a class="headerlink" href="#todo" title="Permalink to this headline">¶</a></h2>
<p>The work is mostly done, but here's what's left, in rough order of priority.</p>
<ul>
<li><p class="first">Most of the various <tt class="docutils literal"><span class="pre">index.txt</span></tt> documents have <em>very</em> short or even
non-existent intro text. Each of those documents needs a good short intro
the content below that point.</p>
</li>
<li><p class="first">The glossary is very perfunctory. It needs to be filled out.</p>
</li>
<li><p class="first">Add more metadata targets: there's lots of places that look like:</p>
<div class="highlight-python"><pre>``File.close()``
~~~~~~~~~~~~~~~~</pre>
</div>
<p>... these should be:</p>
<div class="highlight-python"><pre>.. method:: File.close()</pre>
</div>
<p>That is, use metadata instead of titles.</p>
</li>
<li><p class="first">Add more links -- nearly everything that's an inline code literal
right now can probably be turned into a xref.</p>
<p>See the <tt class="docutils literal"><span class="pre">literals_to_xrefs.py</span></tt> file in <tt class="docutils literal"><span class="pre">_ext</span></tt> -- it's a shell script
to help do this work.</p>
<p>This will probably be a continuing, never-ending project.</p>
</li>
<li><p class="first">Add <a class="reference external" href="http://sphinx.pocoo.org/markup/desc.html#info-field-lists">info field lists</a> where appropriate.</p>
</li>
<li><p class="first">Add <tt class="docutils literal"><span class="pre">..</span> <span class="pre">code-block::</span> <span class="pre"><lang></span></tt> to literal blocks so that they get
highlighted.</p>
</li>
</ul>
</div>
<div class="section" id="s-hints">
<span id="hints"></span><h2>Hints<a class="headerlink" href="#hints" title="Permalink to this headline">¶</a></h2>
<p>Some hints for making things look/read better:</p>
<ul>
<li><p class="first">Whenever possible, use links. So, use <tt class="docutils literal"><span class="pre">:setting:`ADMIN_FOR`</span></tt> instead of
<tt class="docutils literal"><span class="pre">``ADMIN_FOR``</span></tt>.</p>
</li>
<li><p class="first">Some directives (<tt class="docutils literal"><span class="pre">..</span> <span class="pre">setting::</span></tt>, for one) are prefix-style directives;
they go <em>before</em> the unit they're describing. These are known as
"crossref" directives. Others (<tt class="docutils literal"><span class="pre">..</span> <span class="pre">class::</span></tt>, e.g.) generate their own
markup; these should go inside the section they're describing. These are
called "description units".</p>
<p>You can tell which are which by looking at in <tt class="file docutils literal"><span class="pre">_ext/djangodocs.py</span></tt>;
it registers roles as one of the other.</p>
</li>
<li><p class="first">When referring to classes/functions/modules, etc., you'll want to use the
fully-qualified name of the target
(<tt class="docutils literal"><span class="pre">:class:`django.contrib.contenttypes.models.ContentType`</span></tt>).</p>
<p>Since this doesn't look all that awesome in the output -- it shows the
entire path to the object -- you can prefix the target with a <tt class="docutils literal"><span class="pre">~</span></tt>
(that's a tilde) to get just the "last bit" of that path. So
<tt class="docutils literal"><span class="pre">:class:`~django.contrib.contenttypes.models.ContentType`</span></tt> will just
display a link with the title "ContentType".</p>
</li>
</ul>
</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="#">How the Django documentation works</a><ul>
<li><a class="reference internal" href="#django-specific-markup">Django-specific markup</a></li>
<li><a class="reference internal" href="#an-example">An example</a></li>
<li><a class="reference internal" href="#todo">TODO</a></li>
<li><a class="reference internal" href="#hints">Hints</a></li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="contributing.html">Contributing to Django</a></li>
<li>Next: <a href="committers.html">Django committers</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../index.html">Django v1.2 documentation</a>
<ul><li><a href="index.html">Django internals</a>
<ul><li>How the Django documentation works</li></ul>
</li></ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/internals/documentation.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" size="18" />
<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">Jan 28, 2011</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="contributing.html" title="Contributing to Django">previous</a>
|
<a href="index.html" title="Django internals" accesskey="U">up</a>
|
<a href="committers.html" title="Django committers">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
distrib
>
Mandriva
>
2010.1
>
x86_64
>
media
>
main-backports
>
by-pkgid
>
bc8a726fff5aedb19088c6244d3dd008
>
files
>
2771
