我们极其重视文档的一致性和可读性。毕竟，Django 是在需要快速发布新闻的环境下开发的！所以，我们像对待我们的代码一样对待我们的文档：我们期望尽可能频繁地更新它。
一般来说，文档会在以下两种情况时更新：
本节介绍文档作者如何以最有用和最不容易出错的方式修改文档。
Django 文档可在 https://docs.djangoproject.com/ 以网页的形式阅读，但我们以一种更灵活的方式编辑它——一系列的文本文件。这些文件位于 Django 的每个发布分支的顶级目录 docs/ 下。
如果你想开始为我们的文档做贡献，请从源代码库中获取 Django 的开发版本（见 安装开发版本）。开发版有最新、最棒的文档，就像它有最新、最棒的代码一样。在提交者的决定下，我们也会将文档的修正和改进向后移植到最后的发行分支。这是因为让最后一个发行的文档是最新的和正确的是非常有利的（见 版本之间的差异）。
Django 的文档使用 Sphinx 文档系统——基于 docutils。基本思想是将轻量格式话的纯文本转化为 HTML，PDF 或其它任意输出格式。
要在本地构建文档，请安装 Sphinx：
$ python -m pip install Sphinx
...\> py -m pip install Sphinx
然后从 docs 目录下，编译 HTML：
$ make html
...\> make.bat html
编写文档前，你需要阅读 reStructuredText 指引。
Your locally-built documentation will be themed differently than the documentation at docs.djangoproject.com. This is OK! If your changes look good on your local machine, they'll look good on the website.
文档被分为以下几个类别：
教程 通过几步手把手的教学帮助读者创建一个小玩意。
教程的目的是帮助读者尽可能早地实现一些有用的东西，以便给他们带来信心。
解释我们要解决的问题的性质，这样读者就能理解我们要实现的目标。不要觉得你需要从解释事情的运作开始 —— 重要的是读者做什么，而不是你解释什么。参考你所做的事情并在事后进行解释可能会有帮助。
主题指引 旨在在一个较高的层次介绍一个原则或主题。
链接至参考资料而不要重复它。使用示例时，不要不情愿解释对您而言非常基本的事物——它对别人而言可能需要解释。
提供背景信息有助于新人将主题和他们已知的东西联系起来。
参考指南 包含 API 的技术参考。它们描述了 Django 的内部机制的运作，并指导其使用。
让参考资料紧紧围绕着主题。假设读者已经理解了所涉及的基本概念，但需要知道或被提醒 Django 是如何做到的。
参考指南并不是进行一般性解释的地方。如果你发现自己在解释基本概念，你可能想把这些材料移到主题指南中。
操作指南 是带领读者完成关键科目步骤的方法。
在指南中最重要的是用户想要实现什么。一个指南应该始终以结果为导向，而不是专注于 Django 如何实现所讨论的内部细节。
这些指南比教程更高级，并假定有一些关于 Django 如何工作的知识。假设读者已经学习了教程，并且毫不犹豫地让读者回到相应的教程，而不是重复同样的材料。
当使用代词指代一个假设的人时，如 “a user with a session cookie”，应使用性别中性的代词（they/their/them）。而不是：
尽量避免使用将任务或操作的难度降到最低的词语，如 “easily”、“simply”、“just”、“merely”、“straightforward” 等等。人们的经验可能与你的期望不符，当他们发现某个步骤并不像暗示的那样 “straightforward” 或 “simple” 时，可能会感到沮丧。
以下是整个文档中常用术语的一些格式指南：
这些准则规定了我们的 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 的文档。
在文字块中加入 .. 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:: 来定义一个对该环境变量的文档的引用。
除了 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）。
链接到追踪工单（通常为补丁发行说明保留）：
: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 指令。'$' 提示符号，'/' 作为文件系统路径组件分隔符等等）。上面的例子将呈现一个有两个选项卡的代码示例块。第一个将显示：
$ 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"`
This is based on OptiPNG version 0.7.5. Older versions may complain about the
-strip all option being lossy.
有关如何将它们组合在一起的快速示例，请考虑以下假设示例：
首先， 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>`.
接下来，请注意配置的注解方式：
.. 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` 来引用它。
基本上，这就是所有东西融合在一起的方式。
在你提交你的文档之前，运行拼写检查器是个好主意。你需要先安装 sphinxcontrib-spelling 。然后从 docs 目录下，运行 make spelling。错误的词（如果有的话）以及它们出现的文件和行号将被保存到 _build/spelling/output.txt。
如果你遇到假阳性的情况（错误输出实际上是正确的），请采取以下措施之一：
docs/spelling_wordlist （请保持这个列表以字母顺序排列）。查看 本地化 Django 文档，如果你想帮助我们将文档翻译成其它语言。
django-admin 手册页面¶Sphinx 可以为 django-admin 命令生成一个手册页。这是在 docs/conf.py 中配置的。与其他文档输出不同，这个手册页应该包含在 Django 仓库和版本中，作为 docs/man/django-admin.1。在更新文档时不需要更新这个文件，因为它作为发行过程的一部分被更新一次。
要生成更新版本的手册，请在 docs 目录下运行 make man。新的手册页将写在 docs/_build/man/django-admin.1。
12月 07, 2021