我们非常重视文档的一致性和可读性。 毕竟，Django是在新闻环境中创建的！ 因此，我们像处理我们的代码一样对待我们的文档：我们的目标是尽可能多地改进它。
文档更改通常有两种形式：
本节介绍了作者如何以最有用且最不容易出错的方式制作文档更改。
虽然Django的文档旨在在https://docs.djangoproject.com/上以HTML形式阅读，但我们将其编辑为一个文本文件集合，以获得最大的灵活性。 这些文件位于Django版本的顶层docs/目录中。
如果您想开始贡献我们的文档，请从源代码存储库获取Django的开发版本（请参阅安装开发版本）。 开发版本有最新，最伟大的文档，就像它有最新和最伟大的代码。 我们还根据提交者的判断，将文档修订和改进退回到最后一个发布分支。 这是因为最后一个版本的文档是最新和正确的（参见版本之间的差异）是非常有利的。
Django的文档使用Sphinx文档系统，后者又基于docutils。 基本思想是将轻格式的纯文本文档转换为HTML，PDF和任何其他输出格式。
要在本地实际构建文档，您可以使用 - pip install Sphinx 安装Sphinx
然后，构建HTML很容易；只是make html（或make.bat html 在Windows上）从docs目录。
要开始投稿，您需要阅读reStructuredText Primer。 之后，您将要阅读有关用于管理元数据，索引和交叉引用的Sphinx-specific markup。
您的本地制作的文档将与docs.djangoproject.com上的文档不同。 还行吧！ 如果您的本地机器的更改看起来不错，那么网站上看起来会很好。
文档分为几类：
教程通过一系列步骤让读者轻松创作。
教程中的重要内容是帮助读者尽可能早地获得有用的东西，以便让他们有信心。
解释我们正在解决的问题的本质，让读者了解我们正在实现的目标。 不要觉得你需要从解释事物如何运作开始 - 重要的是读者所做的事情，而不是你所解释的。 回顾一下你所做的事情并在之后解释会很有帮助。
主题指南旨在以相当高的水平解释一个概念或主题。
链接到参考资料，而不是重复。 使用示例，不要不情愿地解释对您看起来非常基本的东西 - 这可能是别人需要的解释。
提供背景上下文帮助新人将主题与他们已经知道的内容相连接。
参考指南包含API的技术参考。 他们描述了Django内部机械的功能并指示使用。
保持参考资料紧紧关注主题。 假设读者已经了解了所涉及的基本概念，但需要知道或提醒Django如何做。
参考指南不是一般解释的地方。 如果您发现自己解释基本概念，您可能希望将该材料移动到主题指南。
How-to 指南是代码谱，它们引导你一步一步解决关键问题和使用场景。
在how-to指南中最重要的是用户想要达到的目标。 一个操作方法应该始终以结果为导向，而不是专注于Django如何实现正在讨论的内部细节。
这些指南比教程更先进，并且介绍一些关于Django如何工作的知识。 假设读者已经遵循教程，不要犹豫，将阅读器回到适当的教程，而不是重复相同的材料。
当使用关于假设的人（例如“具有会话cookie的用户”）的代词时，应该使用性别中性代词（他们/他们的/他们）。 代替：
以下是整个文档中常用术语的一些样式指南：
这些准则规定了我们的reST（reStructuredText）文档的格式：
在节标题中，只使用初始词和专有名词。
将文档以80个字符宽度包装，除非代码示例在拆分为两行时显着降低可读性，或者另一个好的原因。
在编写和编辑文档时，要记住的主要事情是，更多的语义标记你可以添加更好。 所以：
Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
是不是几乎有用的：
Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
这是因为Sphinx将为后者生成适当的链接，这极大地有助于读者。
您可以使用~（这是一个波浪号）来为目标前缀，以获得该路径的“最后一位”。 所以:mod:`~django.contrib.auth`将只显示一个标题为“auth”的链接。
使用intersphinx引用Python和Sphinx的文档。
加 .. 代码块:: <lang> 到文字块，以便它们被突出显示。 喜欢依靠自动突出显示使用简单 ::
（两个冒号）。 这有一个好处，如果代码包含一些无效的语法，它不会被突出显示。 添加 .. 代码块:: 蟒蛇例如，尽管语法无效，它将强制突出显示。
使用这些标题样式：
===
One
===
Two
===
Three
-----
Four
~~~~
Five
^^^^
除了Sphinx built-in markup，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
要链接，请使用：选项：`command_name - traceback`（或省略command_name所有命令，如--verbosity）。
链接到Trac门票（通常保留补丁发行说明）：
:ticket:`12345`
我们的新功能政策是：
新功能的所有文档都应该以明确的方式编写，这些功能仅在Django开发版本中可用。 假设文档读者正在使用最新版本，而不是开发版本。
标记新功能的首选方法是将功能文档放在以下位置：“.. versionadded :: X.Y“，后跟一个强制性空行和可选描述（缩进）。
应强调的一般改进或其他更改应使用“.. versionchanged :: X.Y“指令（与上述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 时间到了，没有任何缩进的注释更改。
尽可能优化图像压缩。 对于PNG文件，请使用OptiPNG和AdvanceCOMP的advpng：
$ cd docs/
$ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`
$ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`
这是基于OptiPNG版本0.7.5。 旧版本可能会抱怨 - strip 所有选项是有损的。
有关如何一起适用的快速示例，请考虑此假设示例：
首先，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 list)
A list of all the 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 list should be a tuple
of (Full name, email address). Example::
[('John', 'john@example.com'), ('Mary', 'mary@example.com')]
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`来引用它。
这基本上是一切如何配合在一起。
在提交文档之前，最好运行拼写检查程序。 您需要先安装几个软件包：
然后，从docs目录运行make 拼写。 错误的单词（如果有）及其出现的文件和行号将保存到_build/spelling/output.txt。
如果遇到假阳性（错误输出实际上是正确的），请执行以下操作之一：
docs/spelling_wordlist（请按字母顺序保存列表）。如果您想帮助将文档翻译成其他语言，请参阅Localizing the Django documentation。
django-admin手册页¶Sphinx可以为django-admin命令生成手动页面。 这在docs/conf.py中配置。 与其他文档输出不同，此手册页应包含在Django存储库和版本docs/man/django-admin.1中。 在更新文档时，不需要更新此文件，因为它在发布过程中更新一次。
要生成手册页的更新版本，请在docs目录中运行make man 新的手册页将在docs/_build/man/django-admin.1中写入。
2017年9月6日