编写文档

We place high importance on the consistency and readability of documentation. After all, Django was created in a journalism environment! So we treat our documentation like we treat our code: we aim to improve it as often as possible.

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

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

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

获得原始文档

Django 文档可在 https://docs.djangoproject.com/ 以网页的形式阅读，但我们以一种更灵活的方式编辑它——一系列的文本文件。这些文件位于 Django 的每个发布分支的顶级目录 docs/ 下。

If you’d like to start contributing to our docs, get the development version of Django from the source code repository (see 安装开发版本). The development version has the latest-and-greatest documentation, just as it has the latest-and-greatest code. We also backport documentation fixes and improvements, at the discretion of the merger, to the last release branch. That’s because it’s highly advantageous to have the docs for the last release be up-to-date and correct (see 版本之间的差异).

开始使用 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 指引。

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.

文档是如何组成

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

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

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

    Explain the nature of the problem we’re solving, so that the reader understands what we’re trying to achieve. Don’t feel that you need to begin with explanations of how things work - what matters is what the reader does, not what you explain. It can be helpful to refer back to what you’ve done and explain afterward.

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

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

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

  • Reference guides contain technical references for APIs. They describe the functioning of Django’s internal machinery and instruct in its use.

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

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

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

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

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

书写格式

When using pronouns in reference to a hypothetical person, such as “a user with a session cookie”, gender-neutral pronouns (they/their/them) should be used. Instead of:

  • 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 — the expected pronunciation is “Aitch Tee Tee Pee” and therefore should be preceded by “an” and not “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 — it’s not capitalized.
  • 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” 的链接。

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

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）。

  • 链接到追踪工单（通常为补丁发行说明保留）：

    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

记录新功能

我们对新功能的政策是：

All documentation of new features should be written in a way that clearly designates the features that are only available in the Django development version. Assume documentation readers are using the latest release, not the development version.

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

General improvements or other changes to the APIs that should be emphasized should use the “.. versionchanged:: X.Y“ directive (with the same format as the versionadded mentioned above.

这些 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"`

This is based on OptiPNG version 0.7.5. Older versions may complain about the -strip all option being lossy.

一个例子

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

  • 首先， 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>`.

    We use the Sphinx doc cross-reference element when we want to link to another document as a whole and the ref element when we want to link to an arbitrary location in a document.

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

    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 （请保持这个列表以字母顺序排列）。

Links in documentation can become broken or changed such that they are no longer the canonical link. Sphinx provides a builder that can check whether the links in the documentation are working. From the docs directory, run make linkcheck. Output is printed to the terminal, but can also be found in _build/linkcheck/output.txt and _build/linkcheck/output.json.

Entries that have a status of “working” are fine, those that are “unchecked” or “ignored” have been skipped because they either cannot be checked or have matched ignore rules in the configuration.

Entries that have a status of “broken” need to be fixed. Those that have a status of “redirected” may need to be updated to point to the canonical location, e.g. the scheme has changed http:// → https://. In certain cases, we do not want to update a “redirected” link, e.g. a rewrite to always point to the latest or stable version of the documentation, e.g. /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。