---
title: "编写文档"
version: 3.2
locale: zh-hans
source: https://docs.djangoproject.com/zh-hans/3.2/internals/contributing/writing-documentation/
canonical: https://djangodocs.dev/zh-hans/3.2/internals/contributing/writing-documentation/
---
# 编写文档

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

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

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

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

## 获得原始文档

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

如果你想开始为我们的文档做贡献，请从源代码库中获取 Django 的开发版本（见 [安装开发版本](/zh-hans/3.2/topics/install/#installing-development-version)）。开发版有最新、最棒的文档，就像它有最新、最棒的代码一样。在提交者的决定下，我们也会将文档的修正和改进向后移植到最后的发行分支。这是因为让最后一个发行的文档是最新的和正确的是非常有利的（见 [版本之间的差异](/zh-hans/3.2/intro/whatsnext/#differences-between-doc-versions)）。

## 开始使用 Sphinx

Django  的文档使用 [Sphinx](https://www.sphinx-doc.org/) 文档系统——基于 [docutils](https://docutils.sourceforge.io/)。基本思想是将轻量格式话的纯文本转化为 HTML，PDF 或其它任意输出格式。

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

```console
$ python -m pip install Sphinx
```

*Windows*

```doscon
...\> py -m pip install Sphinx
```

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

```console
$ make html
```

*Windows*

```doscon
...\> make.bat html
```

编写文档前，你需要阅读 [reStructuredText 指引](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html#rst-index)。

Your locally-built documentation will be themed differently than the
documentation at [docs.djangoproject.com](https://docs.djangoproject.com/).
This is OK! If your changes look good on your local machine, they'll look good
on the website.

## 文档是如何组成

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

- [教程](/zh-hans/3.2/intro/) 通过几步手把手的教学帮助读者创建一个小玩意。

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

  解释我们要解决的问题的性质，这样读者就能理解我们要实现的目标。不要觉得你需要从解释事情的运作开始 —— 重要的是读者做什么，而不是你解释什么。参考你所做的事情并在事后进行解释可能会有帮助。
- [主题指引](/zh-hans/3.2/topics/) 旨在在一个较高的层次介绍一个原则或主题。

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

  提供背景信息有助于新人将主题和他们已知的东西联系起来。
- [参考指南](/zh-hans/3.2/ref/) 包含 API 的技术参考。它们描述了 Django 的内部机制的运作，并指导其使用。

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

  参考指南并不是进行一般性解释的地方。如果你发现自己在解释基本概念，你可能想把这些材料移到主题指南中。
- [操作指南](/zh-hans/3.2/howto/) 是带领读者完成关键科目步骤的方法。

  在指南中最重要的是用户想要实现什么。一个指南应该始终以结果为导向，而不是专注于 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`](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#module-sphinx.ext.intersphinx) 来引用 Python 和 Sphinx 的文档。
- 在文字块中加入 `.. code-block:: <lang>`，使其得到高亮。更倾向于使用 `::` （两个冒号）来自动突出显示。这样做的好处是，如果代码中包含一些无效的语法，它就不会被高亮显示。例如，添加 `.. code-block:: python`，就可以在无效的语法中强制高亮显示。
- 为了提高可读性，使用 `.. admonition:: Descriptive title` 而不是 `.. note::`。尽量少使用这些方框。
- 使用这些标题样式：

  ```
  ===
  One
  ===

  Two
  ===

  Three
  -----

  Four
  ~~~~

  Five
  ^^^^
  ```
- 使用 [`:rfc:`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-rfc) 来引用 RFC，如果可能，尽量链接到相关章节。例如，使用 `` :rfc:`2324#section-2.3.2` `` 或 `` :rfc:`Custom link text <2324#section-2.3.2>` ``。
- 使用 [`:pep:`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-pep) 来引用 Python 增强建议（PEP），如果可能的话，尽量链接到相关章节。例如，使用 `` :pep:`20#easter-egg` `` 或 `` :pep:`Easter Egg <20#easter-egg>` ``。
- 使用 [`:mimetype:`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-mimetype) 来指代一个 MIME 类型，除非在代码示例中引用了这个值。
- 使用 [`:envvar:`](https://www.sphinx-doc.org/en/master/usage/referencing.html#role-envvar) 来指代一个环境变量。你可能还需要使用 [`...envvar::`](https://www.sphinx-doc.org/en/master/usage/domains/standard.html#directive-envvar) 来定义一个对该环境变量的文档的引用。

## Django 特有的标记

除了 [Sphinx 的内置标记](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html#rst-index)，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 环境来编写它（即一个 `'$'` 提示符号，`'/'` 作为文件系统路径组件分隔符等等）。

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

```console
$ python manage.py shell
```

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

第二个将显示：

```doscon
...\> 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`：

```console
$ 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` 配置文件可能具有如下总体布局：

  ```rst
  ========
  Settings
  ========

  ...

  .. _available-settings:

  Available settings
  ==================

  ...

  .. _deprecated-settings:

  Deprecated settings
  ===================

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

  ```rst
  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`](https://www.sphinx-doc.org/en/master/usage/referencing.html#role-doc) 交叉引用元素；当我们想链接到文档中的任意的位置时，请使用 [`ref`](https://www.sphinx-doc.org/en/master/usage/referencing.html#role-ref) 元素。
- 接下来，请注意配置的注解方式：

  ```rst
  .. 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](https://pypi.org/project/sphinxcontrib-spelling/) 。然后从 `docs` 目录下，运行 `make spelling`。错误的词（如果有的话）以及它们出现的文件和行号将被保存到 `_build/spelling/output.txt`。

如果你遇到假阳性的情况（错误输出实际上是正确的），请采取以下措施之一：

- 用重音（\`）包围内联代码或品牌／技术名称。
- 查找拼写检查程序发现的同义词。
- 如果，只是如果，你确定你的单词拼写是正确的——将其加入 `docs/spelling_wordlist` （请保持这个列表以字母顺序排列）。

## 翻译文档

查看 [本地化 Django 文档](/zh-hans/3.2/internals/contributing/localizing/#translating-documentation)，如果你想帮助我们将文档翻译成其它语言。

## `django-admin` 手册页面

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

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