我们非常重视文档的一致性和可读性。毕竟，Django是在新闻环境中创建的！因此，我们像处理我们的代码一样对待我们的文档：我们的目标是尽可能多地改进它。
文档更改通常有两种形式：
本节介绍了作者如何以最有用且最不容易出错的方式制作文档更改。
虽然Django的文档旨在在https://docs.djangoproject.com/上以HTML形式阅读，但我们将其编辑为一个文本文件集合，以获得最大的灵活性。这些文件位于Django版本的顶层docs/目录中。
如果您想开始贡献我们的文档，请从源代码存储库获取Django的开发版本（请参阅Installing the development version）。开发版本有最新，最伟大的文档，就像它有最新和最伟大的代码。我们还根据提交者的判断，将文档修订和改进退回到最后一个发布分支。That’s because it’s highly advantageous to have the docs for the last release be up-to-date and correct (see Differences between versions).
Django的文档使用Sphinx文档系统，后者又基于docutils。基本思想是将轻格式的纯文本文档转换为HTML，PDF和任何其他输出格式。
要在本地实际构建文档，您可以使用 - pip install Sphinx 安装Sphinx
注意
构建Django文档需要Sphinx 1.0.2或更高版本。Sphinx还需要Pygments库进行语法高亮；构建Django文档需要Pygments 1.1或更高版本（最新版本应该自动与Sphinx一起安装）。
然后，构建HTML很容易；只需make html（或make.bat html >在Windows上）从docs目录。
要开始投稿，您需要阅读reStructuredText Primer。之后，您将要阅读有关用于管理元数据，索引和交叉引用的Sphinx-specific markup。
当使用关于假设的人（例如“具有会话cookie的用户”）的代词时，应该使用性别中性代词（他们/他们的/他们）。代替：
以下是整个文档中常用术语的一些样式指南：
这些准则规定了我们的reST（reStructuredText）文档的格式：
在节标题中，只使用初始词和专有名词。
将文档以80个字符宽度包装，除非代码示例在拆分为两行时显着降低可读性，或者另一个好的原因。
在编写和编辑文档时，要记住的主要事情是，更多的语义标记你可以添加更好。所以：
Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
是不是几乎有用的：
Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
这是因为Sphinx将为后者生成适当的链接，这极大地有助于读者。您可以添加的有用标记的数量基本上没有限制。
使用intersphinx引用Python和Sphinx的文档。
除了Sphinx内置标记，Django的文档定义了一些额外的描述单元：
设置：
.. setting:: INSTALLED_APPS
要链接到设置，请使用:setting:`INSTALLED_APPS`。
模板标签：
.. templatetag:: regroup
要链接，请使用:ttag:`regroup`。
模板过滤器：
.. templatefilter:: linebreaksbr
要链接，请使用:tfilter:`linebreaksbr`。
字段查找（即Foo.objects.filter(bar__exact=whatever)）：
.. fieldlookup:: exact
要链接，请使用:lookup:`exact`。
django-admin命令：
.. django-admin:: migrate
要链接，请使用:djadmin:`migrate`。
django-admin命令行选项：
.. django-admin-option:: --traceback
要链接，请使用:djadminopt:`--traceback`。
指向Trac ticket的链接（通常保留用于较小发行说明）：
:ticket:`12345`
我们的新功能政策是：
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.
我们首选的标记新功能的方法是使用：.. versionadded :: XY t0 >“，后跟强制性空行和可选内容（缩进）。
需要强调的一般改进或API的其他更改应使用“.. versionchanged :: XY t0 >“指令（格式与上述versionadded相同）。
这些versionadded和versionchanged块应该是“自包含”。换句话说，由于我们只保留这两个版本的注释，注释及其内容，而无需重排，重新编辑或编辑周围文本。例如，不要将新的或已更改的功能的整个描述放在块中，请执行以下操作：
.. class:: Author(first_name, last_name, middle_name=None)
A person who writes books.
``first_name`` is ...
...
``middle_name`` is ...
.. versionchanged:: A.B
The ``middle_name`` argument was added.
将更改的注释注释放在一个部分的底部，而不是顶部。
此外，避免在versionadded或versionchanged块之外引用特定版本的Django。即使在一个块中，这样做通常是多余的，因为这些注释分别呈现为“New in Django A.B：”和“Changed in Django A.B”。
如果函数，属性等，也可以使用versionadded注释，如下所示：
.. attribute:: Author.middle_name
.. versionadded:: A.B
An author's middle name.
当时间到来时，我们可以简单地删除.. versionadded :: A.B注释，
有关如何一起适用的快速示例，请考虑此假设示例：
首先，ref/settings.txt文档可能有如下所示的整体布局：
========
Settings
========
...
.. _available-settings:
Available settings
==================
...
.. _deprecated-settings:
Deprecated settings
===================
...
接下来，topics/settings.txt文档可能包含如下内容：
You can access a :ref:`listing of all available settings
<available-settings>`. For a list of deprecated settings see
:ref:`deprecated-settings`.
You can find both in the :doc:`settings reference document
</ref/settings>`.
当我们要链接到另一个文档作为整体时，我们使用Sphinx doc交叉引用元素，当我们想链接到文档中的任意位置时，使用ref元素。
接下来，请注意设置是如何注释的：
.. setting:: ADMINS
ADMINS
------
Default: ``()`` (Empty tuple)
A tuple that lists people who get code error notifications. When
``DEBUG=False`` and a view raises an exception, Django will email these people
with the full exception information. Each member of the tuple should be a tuple
of (Full name, email address). Example::
(('John', '[email protected]'), ('Mary', '[email protected]'))
Note that Django will email *all* of these people whenever an error happens.
See :doc:`/howto/error-reporting` for more information.
这会将以下标头标记为设置ADMINS的“规范”目标。这意味着任何时候我谈论ADMINS，我可以使用:setting:`ADMINS`来引用它。
这基本上是一切如何配合在一起。
可以做一些小的改进，使文档读取和看起来更好：
各种index.txt文档中的大多数文档具有非常短或甚至不存在的介绍文本。这些文档中的每一个都需要一个很好的简介，低于这一点的内容。
词汇是非常敷衍的。它需要填写。
添加更多元数据目标。很多地方看起来像：
``File.close()``
~~~~~~~~~~~~~~~~
...这些应该是：
.. method:: File.close()
也就是说，使用元数据而不是标题。
添加更多链接 - 几乎所有内联代码字面量现在可能变成一个外部参照。
请参阅_ext中的literals_to_xrefs.py文件 - 它是一个shell脚本，以帮助完成此项工作。
这可能是一个持续，永无止境的项目。
尽可能使用链接。因此，使用:setting:`ADMINS`而不是``ADMINS``。
在适当的地方使用指令。一些指令（例如.. setting ::）是前缀样式指令；他们在他们描述的单位之前去。这些被称为“crossref”指令。其他（例如.. class ::）生成自己的标记；这些应该在他们描述的部分的内部。这些称为“描述单元”。
您可以在_ext/djangodocs.py中查看哪些内容；它注册角色作为其中一个。
将... 代码块:: ＆lt； lang＆gt；添加到文字块，
当引用类/函数/模块等时，你需要使用目标的完全限定名（:class:`django.contrib.contenttypes.models.ContentType`）。
因为这在输出中看起来不是很棒 - 它显示了对象的整个路径 - 你可以在目标前加上一个~（这是一个波浪号）来获得“最后一位”的路径。因此，:class:`~django.contrib.contenttypes.models.ContentType`将只显示一个标题为“ContentType”的链接。
在提交文档之前，最好运行拼写检查程序。您需要先安装几个软件包：
然后，从docs目录运行make 拼写。错误的单词（如果有）及其出现的文件和行号将保存到_build/spelling/output.txt。
如果遇到假阳性（错误输出实际上是正确的），请执行以下操作之一：
如果您想帮助将文档翻译成其他语言，请参阅Localizing the Django documentation。
Sphinx可以为django-admin命令生成手动页面。这在docs/conf.py中配置。与其他文档输出不同，此手册页应包含在Django存储库和版本docs/man/django-admin.1中。在更新文档时，不需要更新此文件，因为它在发布过程中更新一次。
要生成手册页的更新版本，请在docs目录中运行make man新的手册页将在docs/_build/man/django-admin.1中写入。
2015年5月13日