# Django 3.2.11.dev 文档

# 编写文档

我们极其重视文档的一致性和可读性。毕竟，Django 是在需要快速发布新闻的环境下开发的！所以，我们像对待我们的代码一样对待我们的文档：我们期望尽可能频繁地更新它。

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

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

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

## 获得原始文档

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

如果你想开始为我们的文档做贡献，请从源代码库中获取 Django 的开发版本（见 安装开发版本）。开发版有最新、最棒的文档，就像它有最新、最棒的代码一样。在提交者的决定下，我们也会将文档的修正和改进向后移植到最后的发行分支。这是因为让最后一个发行的文档是最新的和正确的是非常有利的（见 版本之间的差异）。

## 开始使用 Sphinx

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）。而不是：

- 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 -- 无连字符。
- MySQL, PostgreSQL, SQLite
- SQL -- 当提及 SQL 时，预期的发音应该是 “Ess Queue Ell” 而不是 “sequel”。因此，在诸如 “Returns an SQL expression” 之类的短语中，“SQL” 前应该使用 “an” 而不是 “a”。
- Python -- 当提及该语言时大写。
- realize, customize, initialize, etc. -- 使用美式的 “ize” 后缀，而不是 “ise”。
- subclass -- 它是一个没有连字符的单个单词，既作为动词（“子类模型”）又作为名词（“创建子类”）。
- Web, World Wide Web, the Web -- 指万维网时注意 Web 总是大写。
- 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” 的链接。

- 使用 `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`）。

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

      :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"`

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>`.

  当我们想链接到另一个文档时，我们使用 `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`` 来引用它。

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

## 拼写检查

在你提交你的文档之前，运行拼写检查器是个好主意。你需要先安装 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`。