编写文档¶
我们非常重视文档的一致性和可读性。毕竟，Django 是在新闻环境中创建的！因此，我们像对待我们的代码一样对待我们的文档：我们努力在尽可能多的时间里改进它。
一般来说，文档会在以下两种情况时更新：
一般改进：通过更清晰的书写和更多示例，更正、修复文档错误，更好的解释功能。
新特性：自上一个版本发布后，添加到框架中的功能文档。
本节介绍文档作者如何以最有用和最不容易出错的方式修改文档。
Django 文档编写流程¶
尽管 Django 的文档旨在以 HTML 形式在 https://docs.djangoproject.com/ 上阅读，但我们将其编辑为一组纯文本文件，使用 reStructuredText 标记语言编写，以实现最大的灵活性。
我们从存储库的开发版本中工作，因为它包含了最新的文档，就像它包含了最新的代码一样。
我们还会根据合并者的判断，将文档修复和改进内容反向移植到上一个发布分支。这是因为让上一个版本的文档保持最新和正确是有好处的（参见 版本之间的差异）。
Django 的文档使用 Sphinx 文档系统——基于 docutils。基本思想是将轻量格式话的纯文本转化为 HTML，PDF 或其它任意输出格式。
Sphinx 包括一个 sphinx-build 命令，用于将 reStructuredText 转换为其他格式，例如 HTML 和 PDF。这个命令是可配置的，但 Django 文档包括一个 Makefile，提供了一个更简短的 make html 命令。
文档是如何组成¶
文档被分为以下几个类别：
教程 通过几步手把手的教学帮助读者创建一个小玩意。
教程的目的是帮助读者尽可能早地实现一些有用的东西，以便给他们带来信心。
解释我们正在解决的问题的性质，以便读者理解我们试图实现什么。不必从事物如何工作的解释开始 - 重要的是读者做什么，而不是你解释什么。在完成操作后回顾并解释可以是有帮助的。
主题指引 旨在在一个较高的层次介绍一个原则或主题。
链接至参考资料而不要重复它。使用示例时，不要不情愿解释对您而言非常基本的事物——它对别人而言可能需要解释。
提供背景信息有助于新人将主题和他们已知的东西联系起来。
参考指南 包含 API 的技术参考。它们描述了 Django 内部机制的运作方式，并指导如何使用它。
让参考资料紧紧围绕着主题。假设读者已经理解了所涉及的基本概念，但需要知道或被提醒 Django 是如何做到的。
参考指南并不是进行一般性解释的地方。如果你发现自己在解释基本概念，你可能想把这些材料移到主题指南中。
操作指南 是带领读者完成关键科目步骤的方法。
在指南中最重要的是用户想要实现什么。一个指南应该始终以结果为导向，而不是专注于 Django 如何实现所讨论的内部细节。
这些指南比教程更高级，并假定有一些关于 Django 如何工作的知识。假设读者已经学习了教程，并且毫不犹豫地让读者回到相应的教程，而不是重复同样的材料。
如何开始贡献文档¶
克隆 Django 存储库到您的本地计算机¶
如果你想开始为我们的文档做贡献，可以从源代码仓库获取 Django 的开发版本（参见：安装开发版本）：
$ git clone https://github.com/django/django.git
...\> git clone https://github.com/django/django.git
如果你计划提交这些更改，你可能会发现创建 Django 仓库的一个分支并克隆这个分支会很有用。
建立一个虚拟环境并安装依赖项¶
创建并激活一个虚拟环境，然后安装依赖项：
$ python -m venv .venv
$ source .venv/bin/activate
$ python -m pip install -r docs/requirements.txt
在本地构建文档¶
我们可以从 docs 目录生成 HTML 输出：
$ cd docs
$ make html
...\> cd docs
...\> make.bat html
你在本地构建的文档可以在 _build/html/index.html 中访问，并且可以在任何网页浏览器中查看，尽管它的主题与 docs.djangoproject.com 上的文档不同。这没关系！如果你的更改在本地看起来不错，它们在网站上也会看起来不错。
对文档进行编辑¶
源文件是位于 docs/ 目录中的 .txt 文件。
这些文件是用 reStructuredText 标记语言编写的。要了解这种标记语言，请参阅 reStructuredText 参考手册。
要编辑此页面，例如，我们会编辑文件 docs/internals/contributing/writing-documentation.txt，然后使用 make html 重新构建 HTML。
拼写检查¶
在提交文档之前，最好运行拼写检查器。首先，你需要安装 sphinxcontrib-spelling。然后从 docs 目录中运行 make spelling。错误的单词（如果有的话）以及它们出现的文件和行号将保存到 _build/spelling/output.txt。
如果你遇到假阳性的情况（错误输出实际上是正确的），请采取以下措施之一：
用双反引号（``）括起内联代码或品牌/技术名称。
查找拼写检查程序发现的同义词。
如果，只是如果，你确定你的单词拼写是正确的——将其加入
docs/spelling_wordlist（请保持这个列表以字母顺序排列）。
链接检查¶
文档中的链接可能会损坏或更改，以至于它们不再是规范链接。Sphinx 提供了一个构建器，可以检查文档中的链接是否正常工作。从 docs 目录中运行 make linkcheck。输出将打印到终端，但也可以在 _build/linkcheck/output.txt 和 _build/linkcheck/output.json 中找到。
状态为 "working" 的条目是正常的，而状态为 "unchecked" 或 "ignored" 的条目已被跳过，因为它们要么无法检查，要么与配置中的忽略规则匹配。
状态为 "broken" 的条目需要修复。而状态为 "redirected" 的条目可能需要更新，以指向规范位置，例如，方案已更改为 http:// → https://。在某些情况下，我们不希望更新 "redirected" 链接，例如，重定向始终指向文档的最新或稳定版本，例如，/en/stable/ → /en/3.2/。
书写格式¶
在提及假设的人时，例如 "一个带有会话 cookie 的用户"，应该使用性别中性的代词 (they/their/them)。而不是：
he 或 she……使用 they。
him 或 her... 使用 them。
his 或 her……使用 their。
his 或 hers... 使用 theirs。
himself 或 herself... 使用 themselves。
尽量避免使用将任务或操作的难度降到最低的词语，如 “easily”、“simply”、“just”、“merely”、“straightforward” 等等。人们的经验可能与你的期望不符，当他们发现某个步骤并不像暗示的那样 “straightforward” 或 “simple” 时，可能会感到沮丧。
常用术语¶
以下是整个文档中常用术语的一些格式指南：
Django -- 当提及该框架时，大写 Django。它仅在 Python 代码中和 djangoproject.com 徽标中使用小写字母。
email -- 无连字符。
HTTP -- 预期的发音是 "Aitch Tee Tee Pee"，因此应该用 "an" 而不是 "a"。
MySQL, PostgreSQL, SQLite
SQL -- 当提及 SQL 时，预期的发音应该是 “Ess Queue Ell” 而不是 “sequel”。因此，在诸如 “Returns an SQL expression” 之类的短语中，“SQL” 前应该使用 “an” 而不是 “a”。
Python -- 当提及该语言时大写。
realize, customize, initialize, etc. -- 使用美式的 “ize” 后缀，而不是 “ise”。
subclass -- 它是一个没有连字符的单个单词，既作为动词（“子类模型”）又作为名词（“创建子类”）。
the web，web framework -- 不需要大写。
website -- 用一个单词表示，不大写。
Django 专用术语¶
model -- 它不是大写的。
template -- 它不是大写的。
URLconf -- 使用了三个大写字母，在 “conf” 之前没有空格。
view -- 它不是大写的。
reStructuredText 文件语法指南¶
这些准则规定了我们的 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” 的链接。所有 Python 代码块都应使用 blacken-docs 自动格式化工具进行格式化。如果已配置
pre-commit，它将自动运行此工具。使用
intersphinx来引用 Python 和 Sphinx 的文档。在文字块中加入
.. code-block:: <lang>，使其得到高亮。更倾向于使用::（两个冒号）来自动突出显示。这样做的好处是，如果代码中包含一些无效的语法，它就不会被高亮显示。例如，添加.. code-block:: python，就可以在无效的语法中强制高亮显示。为了提高可读性，使用
.. admonition:: Descriptive title而不是.. note::。尽量少使用这些方框。使用这些标题样式：
=== One === Two === Three ----- Four ~~~~ Five ^^^^
使用
:rfc:来引用 RFC，如果可能，尽量链接到相关章节。例如，使用:rfc:`2324#section-2.3.2`或:rfc:`Custom link text <2324#section-2.3.2>`。使用
:pep:来引用 Python 增强建议（PEP），如果可能的话，尽量链接到相关章节。例如，使用:pep:`20#easter-egg`或:pep:`Easter Egg <20#easter-egg>`。使用
:mimetype:来指代一个 MIME 类型，除非在代码示例中引用了这个值。使用
:envvar:来指代一个环境变量。你可能还需要使用...envvar::来定义一个对该环境变量的文档的引用。
Django 特有的标记¶
除了 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
为了链接，请使用
:option:`command_name --trackback（或者省略command_name，用于所有命令共享的选项，如--verbosity）。Trac 问题的链接（通常用于补丁发布说明）：
:ticket:`12345`
Django 的文档使用一个自定义的 console 指令，用于记录涉及 django-admin、manage.py、python 等的命令行实例。在 HTML 文档中，它渲染了一个双选项卡 UI，其中一个选项卡显示 Unix 风格的命令提示符，第二个选项卡显示 Windows 提示符。
例如，你可以替换这个片段：
use this command:
.. code-block:: console
$ python manage.py shell
用这个替代：
use this command:
.. console::
$ python manage.py shell
请注意两件事：
你通常会替换出现的
.. code-block:: console指令。你不需要改变代码例子的实际内容。你仍然假设 Unix-y 环境来编写它（即一个
'$'提示符号，'/'作为文件系统路径组件分隔符等等）。
上面的例子将呈现一个有两个选项卡的代码示例块。第一个将显示：
$ python manage.py shell
与 .. code-block:: console 所呈现的内容相比没有变化）。
第二个将显示：
...\> py manage.py shell
记录新功能¶
我们对新功能的政策是：
所有新功能的文档应以一种明确指出这些功能仅在 Django 开发版本中可用的方式编写。假设文档读者使用的是最新发布版，而不是开发版本。
我们首选的标记新特性的方法是在特性的文档前加上。".. versionadded:: X.Y"，后面是一个强制性的空行和一个可选的描述（缩进）。
对 API 进行的一般改进或其他需要强调的更改应使用 ".. 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 all 选项进行丢失投诉。
一个例子¶
有关如何将它们组合在一起的快速示例，请考虑以下假设示例：
首先，
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`来引用它。
基本上，这就是所有东西融合在一起的方式。
翻译文档¶
查看 本地化 Django 文档，如果你想帮助我们将文档翻译成其它语言。
django-admin 手册页面¶
Sphinx 可以为 django-admin 命令生成一个手册页。这是在 docs/conf.py 中配置的。与其他文档输出不同，这个手册页应该包含在 Django 仓库和版本中，作为 docs/man/django-admin.1。在更新文档时不需要更新这个文件，因为它作为发行过程的一部分被更新一次。
要生成更新版本的手册，请在 docs 目录下运行 make man。新的手册页将写在 docs/_build/man/django-admin.1。
