<!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>Writing documentation — Django 1.4.13 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.4.13', 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.4.13 documentation" href="../../index.html" /> <link rel="up" title="Contributing to Django" href="index.html" /> <link rel="next" title="Localizing Django" href="localizing.html" /> <link rel="prev" title="Branch policy" href="writing-code/branch-policy.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 1.4.13 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="writing-code/branch-policy.html" title="Branch policy">previous</a> | <a href="../index.html" title="Django internals" accesskey="U">up</a> | <a href="localizing.html" title="Localizing Django">next</a> »</div> </div> <div id="bd"> <div id="yui-main"> <div class="yui-b"> <div class="yui-g" id="internals-contributing-writing-documentation"> <div class="section" id="s-writing-documentation"> <span id="writing-documentation"></span><h1>Writing documentation<a class="headerlink" href="#writing-documentation" title="Permalink to this headline">¶</a></h1> <p>We place a high importance on consistency and readability of documentation. After all, Django was created in a journalism environment! So we treat our documentation like we treat our code: we aim to improve it as often as possible.</p> <p>Documentation changes generally come in two forms:</p> <ul class="simple"> <li>General improvements: typo corrections, error fixes and better explanations through clearer writing and more examples.</li> <li>New features: documentation of features that have been added to the framework since the last release.</li> </ul> <p>This section explains how writers can craft their documentation changes in the most useful and least error-prone ways.</p> <div class="section" id="s-getting-the-raw-documentation"> <span id="getting-the-raw-documentation"></span><h2>Getting the raw documentation<a class="headerlink" href="#getting-the-raw-documentation" title="Permalink to this headline">¶</a></h2> <p>Though Django’s documentation is intended to be read as HTML at <a class="reference external" href="https://docs.djangoproject.com/">https://docs.djangoproject.com/</a>, we edit it as a collection of text files for maximum flexibility. These files live in the top-level <tt class="docutils literal"><span class="pre">docs/</span></tt> directory of a Django release.</p> <p>If you’d like to start contributing to our docs, get the development version of Django from the source code repository (see <a class="reference internal" href="../../topics/install.html#installing-development-version"><em>Installing the development version</em></a>). The development version has the latest-and-greatest documentation, just as it has latest-and-greatest code. Generally, we only revise documentation in the development version, as our policy is to freeze documentation for existing releases (see <a class="reference internal" href="../../intro/whatsnext.html#differences-between-doc-versions"><em>Differences between versions</em></a>).</p> </div> <div class="section" id="s-getting-started-with-sphinx"> <span id="getting-started-with-sphinx"></span><h2>Getting started with Sphinx<a class="headerlink" href="#getting-started-with-sphinx" title="Permalink to this headline">¶</a></h2> <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">sudo</span> <span class="pre">pip</span> <span class="pre">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">Building the Django documentation requires Sphinx 1.0.2 or newer. Sphinx also requires the <a class="reference external" href="http://pygments.org">Pygments</a> library for syntax highlighting; building the Django documentation requires Pygments 1.1 or newer (a new-enough version should automatically be installed along with Sphinx).</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> (or <tt class="docutils literal"><span class="pre">make.bat</span> <span class="pre">html</span></tt> on Windows) 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#rst-primer" title="(in Sphinx v1.2.2)"><em class="xref std std-ref">reStructuredText Primer</em></a>. After that, you’ll want to read about the <a class="reference external" href="http://sphinx.pocoo.org/markup/index.html#sphinxmarkup" title="(in Sphinx v1.2.2)"><em class="xref std std-ref">Sphinx-specific markup</em></a> that’s used to manage metadata, indexing, and cross-references.</p> </div> <div class="section" id="s-commonly-used-terms"> <span id="commonly-used-terms"></span><h2>Commonly used terms<a class="headerlink" href="#commonly-used-terms" title="Permalink to this headline">¶</a></h2> <p>Here are some style guidelines on commonly used terms throughout the documentation:</p> <ul class="simple"> <li><strong>Django</strong> – when referring to the framework, capitalize Django. It is lowercase only in Python code and in the djangoproject.com logo.</li> <li><strong>email</strong> – no hyphen.</li> <li><strong>MySQL</strong>, <strong>PostgreSQL</strong>, <strong>SQLite</strong></li> <li><strong>Python</strong> – when referring to the language, capitalize Python.</li> <li><strong>realize</strong>, <strong>customize</strong>, <strong>initialize</strong>, etc. – use the American “ize” suffix, not “ise.”</li> <li><strong>subclass</strong> – it’s a single word without a hyphen, both as a verb (“subclass that model”) and as a noun (“create a subclass”).</li> <li><strong>Web</strong>, <strong>World Wide Web</strong>, <strong>the Web</strong> – note Web is always capitalized when referring to the World Wide Web.</li> <li><strong>Web site</strong> – use two words, with Web capitalized.</li> </ul> </div> <div class="section" id="s-django-specific-terminology"> <span id="django-specific-terminology"></span><h2>Django-specific terminology<a class="headerlink" href="#django-specific-terminology" title="Permalink to this headline">¶</a></h2> <ul class="simple"> <li><strong>model</strong> – it’s not capitalized.</li> <li><strong>template</strong> – it’s not capitalized.</li> <li><strong>URLconf</strong> – use three capitalized letters, with no space before “conf.”</li> <li><strong>view</strong> – it’s not capitalized.</li> </ul> </div> <div class="section" id="s-guidelines-for-restructuredtext-files"> <span id="guidelines-for-restructuredtext-files"></span><h2>Guidelines for reStructuredText files<a class="headerlink" href="#guidelines-for-restructuredtext-files" title="Permalink to this headline">¶</a></h2> <p>These guidelines regulate the format of our reST (reStructuredText) documentation:</p> <ul> <li><p class="first">In section titles, capitalize only initial words and proper nouns.</p> </li> <li><p class="first">Wrap the documentation at 80 characters wide, unless a code example is significantly less readable when split over two lines, or for another good reason.</p> </li> <li><p class="first">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> </li> <li><p class="first">Use <a class="reference external" href="http://sphinx.pocoo.org/ext/intersphinx.html#module-sphinx.ext.intersphinx" title="(in Sphinx v1.2.2)"><tt class="xref py py-mod docutils literal"><span class="pre">intersphinx</span></tt></a> to reference Python’s and Sphinx’ documentation.</p> </li> </ul> </div> <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-documenting-new-features"> <span id="s-id5"></span><span id="documenting-new-features"></span><span id="id5"></span><h2>Documenting new features<a class="headerlink" href="#documenting-new-features" title="Permalink to this headline">¶</a></h2> <p>Our policy for new features is:</p> <blockquote> <div>All documentation of new features should be written in a way that clearly designates the features are only available in the Django development version. Assume documentation readers are using the latest release, not the development version.</div></blockquote> <p>Our preferred way for marking new features is by prefacing the features’ documentation with: “<tt class="docutils literal"><span class="pre">..</span> <span class="pre">versionadded::</span> <span class="pre">X.Y</span></tt>”, followed by an optional one line comment and a mandatory blank line.</p> <p>General improvements, or other changes to the APIs that should be emphasized should use the “<tt class="docutils literal"><span class="pre">..</span> <span class="pre">versionchanged::</span> <span class="pre">X.Y</span></tt>” directive (with the same format as the <tt class="docutils literal"><span class="pre">versionadded</span></tt> mentioned above.</p> </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="p">..</span> <span class="nt">_available-settings:</span> <span class="gh">Available settings</span> <span class="gh">==================</span> <span class="cp">...</span> <span class="p">..</span> <span class="nt">_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 :doc:`settings reference document <span class="nt"></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" title="(in Sphinx v1.2.2)"><tt class="xref rst rst-role docutils literal"><span class="pre">doc</span></tt></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" title="(in Sphinx v1.2.2)"><tt class="xref rst rst-role docutils literal"><span class="pre">ref</span></tt></a> element when we want to link to an arbitrary location in a document.</p> </li> <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-improving-the-documentation"> <span id="s-id6"></span><span id="improving-the-documentation"></span><span id="id6"></span><h2>Improving the documentation<a class="headerlink" href="#improving-the-documentation" title="Permalink to this headline">¶</a></h2> <p>A few small improvements can be made to make the documentation read and look better:</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. Lots of places 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">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">Use directives where appropriate. Some directives (e.g. <tt class="docutils literal"><span class="pre">..</span> <span class="pre">setting::</span></tt>) are prefix-style directives; they go <em>before</em> the unit they’re describing. These are known as “crossref” directives. Others (e.g. <tt class="docutils literal"><span class="pre">..</span> <span class="pre">class::</span></tt>) 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">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> <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="#">Writing documentation</a><ul> <li><a class="reference internal" href="#getting-the-raw-documentation">Getting the raw documentation</a></li> <li><a class="reference internal" href="#getting-started-with-sphinx">Getting started with Sphinx</a></li> <li><a class="reference internal" href="#commonly-used-terms">Commonly used terms</a></li> <li><a class="reference internal" href="#django-specific-terminology">Django-specific terminology</a></li> <li><a class="reference internal" href="#guidelines-for-restructuredtext-files">Guidelines for reStructuredText files</a></li> <li><a class="reference internal" href="#django-specific-markup">Django-specific markup</a></li> <li><a class="reference internal" href="#documenting-new-features">Documenting new features</a></li> <li><a class="reference internal" href="#an-example">An example</a></li> <li><a class="reference internal" href="#improving-the-documentation">Improving the documentation</a></li> </ul> </li> </ul> <h3>Browse</h3> <ul> <li>Prev: <a href="writing-code/branch-policy.html">Branch policy</a></li> <li>Next: <a href="localizing.html">Localizing Django</a></li> </ul> <h3>You are here:</h3> <ul> <li> <a href="../../index.html">Django 1.4.13 documentation</a> <ul><li><a href="../index.html">Django internals</a> <ul><li><a href="index.html">Contributing to Django</a> <ul><li>Writing documentation</li></ul> </li></ul></li></ul> </li> </ul> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../../_sources/internals/contributing/writing-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" /> <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">May 15, 2014</p> </div> </div> <div id="ft"> <div class="nav"> « <a href="writing-code/branch-policy.html" title="Branch policy">previous</a> | <a href="../index.html" title="Django internals" accesskey="U">up</a> | <a href="localizing.html" title="Localizing Django">next</a> »</div> </div> </div> <div class="clearer"></div> </div> </body> </html>