编写文档

我们非常重视文档的一致性和可读性。毕竟，Django 是在新闻环境中创建的！因此，我们像对待我们的代码一样对待我们的文档：我们努力在尽可能多的时间里改进它。

一般来说，文档会在以下两种情况时更新：

  • 一般改进：通过更清晰的书写和更多示例，更正、修复文档错误，更好的解释功能。
  • 新特性：自上一个版本发布后，添加到框架中的功能文档。

本节介绍文档作者如何以最有用和最不容易出错的方式修改文档。

获得原始文档

尽管 Django 的文档是打算作为 HTML 在 https://docs.djangoproject.com/ 上阅读的，但我们将其编辑为一组文本文件，以实现最大的灵活性。这些文件位于 Django 发布的顶级 docs/ 目录中。

如果你想开始为我们的文档做贡献，请从源代码存储库获取 Django 的开发版本（参见 安装开发版本）。开发版本具有最新和最棒的文档，就像它具有最新和最棒的代码一样。我们还会根据合并者的判断，将文档修复和改进回溯到上一个发布分支。这是因为让上一个发布版本的文档保持最新和正确非常有利（参见 版本之间的差异）。

开始使用 Sphinx

Django 的文档使用 Sphinx 文档系统——基于 docutils。基本思想是将轻量格式话的纯文本转化为 HTML，PDF 或其它任意输出格式。

要在本地构建文档，请安装 Sphinx：

Linux/MacOS     Windows

  1. $ python -m pip install Sphinx
  1. ...\> py -m pip install Sphinx

然后从 docs 目录下，编译 HTML：

Linux/MacOS     Windows

  1. $ make html
  1. ...\> make.bat html

编写文档前，你需要阅读 reStructuredText 指引。

你在本地构建的文档可以在 docs/_build/html/index.html 处访问，并且可以在任何网络浏览器中查看，尽管它的主题与 docs.djangoproject.com 上的文档不同。这没问题！如果你的更改在你的本地机器上看起来不错，它们在网站上也会看起来不错。

文档是如何组成

文档被分为以下几个类别：

  • 教程 通过几步手把手的教学帮助读者创建一个小玩意。

    教程的目的是帮助读者尽可能早地实现一些有用的东西，以便给他们带来信心。

    解释我们正在解决的问题的性质，以便读者理解我们试图实现什么。不必从事物如何工作的解释开始 - 重要的是读者做什么，而不是你解释什么。在完成操作后回顾并解释可以是有帮助的。

  • 主题指引 旨在在一个较高的层次介绍一个原则或主题。

    链接至参考资料而不要重复它。使用示例时，不要不情愿解释对您而言非常基本的事物——它对别人而言可能需要解释。

    提供背景信息有助于新人将主题和他们已知的东西联系起来。

  • 参考指南 包含 API 的技术参考。它们描述了 Django 内部机制的运作方式，并指导如何使用它。

    让参考资料紧紧围绕着主题。假设读者已经理解了所涉及的基本概念，但需要知道或被提醒 Django 是如何做到的。

    参考指南并不是进行一般性解释的地方。如果你发现自己在解释基本概念，你可能想把这些材料移到主题指南中。

  • 操作指南 是带领读者完成关键科目步骤的方法。

    在指南中最重要的是用户想要实现什么。一个指南应该始终以结果为导向，而不是专注于 Django 如何实现所讨论的内部细节。

    这些指南比教程更高级，并假定有一些关于 Django 如何工作的知识。假设读者已经学习了教程，并且毫不犹豫地让读者回到相应的教程，而不是重复同样的材料。

书写格式

在提及假设的人时，例如 “一个带有会话 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 个字符宽换行，除非一个代码例子被分割成两行时可读性明显降低，或者有其他好的理由。

  • 在编写和编辑文档时要记住的主要事情是，你能添加的更多语义化标记越多越好。因此：

    1. Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...

    远远不如：

    1. 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::。尽量少使用这些方框。

  • 使用这些标题样式：

    1. ===
    2. One
    3. ===
    5. Two
    6. ===
    8. Three
    9. -----
    11. Four
    12. ~~~~
    14. Five
    15. ^^^^

  • 使用 :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:: 来定义一个对该环境变量的文档的引用。

Changed in Django 4.2:

Django 文档中的所有 Python 代码块都已使用 blacken-docs 进行了重新格式化。

Django 特有的标记

除了 Sphinx 的内置标记，Django 的文档定义了一些额外的描述单元：

  • 配置：

    1. .. setting:: INSTALLED_APPS

    为了连接配置，请使用配置 :setting:`INSTALLED_APPS` 。

  • 模板标签：

    1. .. templatetag:: regroup

    为了链接，请使用 :ttag:`regroup` 。

  • 模板过滤器：

    1. .. templatefilter:: linebreaksbr

    为了链接，请使用 :tfilter:`linebreaksbr` 。

  • 字段查找（例如 Foo.objects.filter(bar__exact=whatever)）：

    1. .. fieldlookup:: exact

    为了链接，请使用 :lookup:`exact` 。

  • django-admin 命令：

    1. .. django-admin:: migrate

    为了链接，请使用 :djadmin:`migrate` 。

  • ``django-admin`命令行选项：

    1. .. django-admin-option:: --traceback

    为了链接，请使用 :option:`command_name --trackback （或者省略 command_name，用于所有命令共享的选项，如 --verbosity）。

  • Trac 问题的链接（通常用于补丁发布说明）：

    1. :ticket:`12345`

Django 的文档使用一个自定义的 console 指令，用于记录涉及 django-admin、manage.py、python 等的命令行实例。在 HTML 文档中，它渲染了一个双选项卡 UI，其中一个选项卡显示 Unix 风格的命令提示符，第二个选项卡显示 Windows 提示符。

例如，你可以替换这个片段：

  1. use this command:
  3. .. code-block:: console
  5.     $ python manage.py shell

用这个替代：

  1. use this command:
  3. .. console::
  5.     $ python manage.py shell

请注意两件事：

  • 你通常会替换出现的 .. code-block:: console 指令。
  • 你不需要改变代码例子的实际内容。你仍然假设 Unix-y 环境来编写它（即一个 '$' 提示符号，'/' 作为文件系统路径组件分隔符等等）。

上面的例子将呈现一个有两个选项卡的代码示例块。第一个将显示：

  1. $ python manage.py shell

与 .. code-block:: console 所呈现的内容相比没有变化）。

第二个将显示：

  1. ...\> py manage.py shell

记录新功能

我们对新功能的政策是：

所有新功能的文档应以一种明确指出这些功能仅在 Django 开发版本中可用的方式编写。假设文档读者使用的是最新发布版，而不是开发版本。

我们首选的标记新特性的方法是在特性的文档前加上。”.. versionadded:: X.Y“，后面是一个强制性的空行和一个可选的描述（缩进）。

对 API 进行的一般改进或其他需要强调的更改应使用 “.. versionchanged:: X.Y“ 指令（格式与上面提到的 versionadded 相同）。

这些 versionadded 和 versionchanged 块应该是 “自包含的”。换句话说，由于我们只保留这些注释两个发布版，最好能够删除注释及其内容，而不必重新排列、重新缩进或编辑周围的文本。例如，不要将新功能或更改功能的整个描述放在一个块中，而是像这样做：

  1. .. class:: Author(first_name, last_name, middle_name=None)
  3.     A person who writes books.
  5.     ``first_name`` is ...
  7.     ...
  9.     ``middle_name`` is ...
  11.     .. versionchanged:: A.B
  13.         The ``middle_name`` argument was added.

把修改后的注解说明放在一个章节的底部，而不是顶部。

另外，避免在 versionadded 或 versionchanged 块之外提及 Django 的特定版本。即使在代码块中，这样做也是多余的，因为这些注解分别呈现为 “New in Django A.B:” 和 “Changed in Django A.B”。

如果添加了一个函数、属性等，也可以像这样使用 versionadded 注释：

  1. .. attribute:: Author.middle_name
  3.     .. versionadded:: A.B
  5.     An author's middle name.

我们可以删除 .. versionadded:: A.B 注解，而不需要在时间上做任何缩进的改变。

最小化图像

尽可能地优化图像压缩。对于 PNG 文件，使用 OptiPNG 和 AdvanceCOMP 的 advpng：

  1. $ cd docs
  2. $ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`
  3. $ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`

这是基于 OptiPNG 版本 0.7.5。旧版本可能会对 -strip all 选项进行丢失投诉。

一个例子

有关如何将它们组合在一起的快速示例，请考虑以下假设示例：

  • 首先， ref/settings.txt 配置文件可能具有如下总体布局：

    1. ========
    2. Settings
    3. ========
    5. ...
    7. .. _available-settings:
    9. Available settings
    10. ==================
    12. ...
    14. .. _deprecated-settings:
    16. Deprecated settings
    17. ===================
    19. ...

  • 接下来， topics/settings.txt 配置文档可能包含以下内容：

    1. You can access a :ref:`listing of all available settings
    2. <available-settings>`. For a list of deprecated settings see
    3. :ref:`deprecated-settings`.
    5. You can find both in the :doc:`settings reference document
    6. </ref/settings>`.

    当我们想要链接到另一个文档的整体时，我们使用 Sphinx 的 doc 交叉引用元素，而当我们想要链接到文档中的任意位置时，我们使用 ref 元素。

  • 接下来，请注意配置的注解方式：

    1. .. setting:: ADMINS
    3. ADMINS
    4. ======
    6. Default: ``[]`` (Empty list)
    8. A list of all the people who get code error notifications. When
    9. ``DEBUG=False`` and a view raises an exception, Django will email these people
    10. with the full exception information. Each member of the list should be a tuple
    11. of (Full name, email address). Example::
    13.     [("John", "john@example.com"), ("Mary", "mary@example.com")]
    15. Note that Django will email *all* of these people whenever an error happens.
    16. See :doc:`/howto/error-reporting` for more information.

    这标志着下面的标题是配置 ADMINS 的 “标准” 目标。这意味着当我谈到 ADMINS 时，我可以用 :setting:`ADMINS` 来引用它。

基本上，这就是所有东西融合在一起的方式。

拼写检查

在提交文档之前，最好运行拼写检查器。首先，你需要安装 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/。

翻译文档

查看 本地化 Django 文档，如果你想帮助我们将文档翻译成其它语言。

django-admin 手册页面

Sphinx 可以为 django-admin 命令生成一个手册页。这是在 docs/conf.py 中配置的。与其他文档输出不同，这个手册页应该包含在 Django 仓库和版本中，作为 docs/man/django-admin.1。在更新文档时不需要更新这个文件，因为它作为发行过程的一部分被更新一次。

要生成更新版本的手册，请在 docs 目录下运行 make man。新的手册页将写在 docs/_build/man/django-admin.1。