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

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

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

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

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

## Django 文档编写流程

尽管 Django 的文档旨在以 HTML 形式在 <https://docs.djangoproject.com/> 上阅读，但我们将其编辑为一组纯文本文件，使用 reStructuredText 标记语言编写，以实现最大的灵活性。

我们从存储库的开发版本中工作，因为它包含了最新的文档，就像它包含了最新的代码一样。

我们还会根据合并者的判断，将文档修复和改进内容反向移植到上一个发布分支。这是因为让上一个版本的文档保持最新和正确是有好处的（参见 [版本之间的差异](/zh-hans/5.1/intro/whatsnext/#differences-between-doc-versions)）。

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

Sphinx 包括一个 `sphinx-build` 命令，用于将 reStructuredText 转换为其他格式，例如 HTML 和 PDF。这个命令是可配置的，但 Django 文档包括一个 `Makefile`，提供了一个更简短的 `make html` 命令。

## 文档是如何组成

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

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

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

  解释我们正在解决的问题的性质，以便读者理解我们试图实现什么。不必从事物如何工作的解释开始 - 重要的是读者做什么，而不是你解释什么。在完成操作后回顾并解释可以是有帮助的。
- [主题指引](/zh-hans/5.1/topics/) 旨在在一个较高的层次介绍一个原则或主题。

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

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

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

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

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

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

## 如何开始贡献文档

### 克隆 Django 存储库到您的本地计算机

如果你想开始为我们的文档做贡献，可以从源代码仓库获取 Django 的开发版本（参见：[安装开发版本](/zh-hans/5.1/topics/install/#installing-development-version)）：

```console
$ git clone https://github.com/django/django.git
```

*Windows*

```doscon
...\> git clone https://github.com/django/django.git
```

如果你计划提交这些更改，你可能会发现创建 Django 仓库的一个分支并克隆这个分支会很有用。

### 建立一个虚拟环境并安装依赖项

创建并激活一个虚拟环境，然后安装依赖项：

```shell
$ python -m venv .venv
$ source .venv/bin/activate
$ python -m pip install -r docs/requirements.txt
```

### 在本地构建文档

我们可以从 `docs` 目录生成 HTML 输出：

```console
$ cd docs
$ make html
```

*Windows*

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

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

### 对文档进行编辑

源文件是位于 `docs/` 目录中的 `.txt` 文件。

这些文件是用 reStructuredText 标记语言编写的。要了解这种标记语言，请参阅 [reStructuredText 参考手册](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html#rst-index)。

要编辑此页面，例如，我们会编辑文件 [docs/internals/contributing/writing-documentation.txt](https://github.com/django/django/blob/stable/5.1.x/docs/internals/contributing/writing-documentation.txt)，然后使用 `make html` 重新构建 HTML。

### 拼写检查

在提交文档之前，最好运行拼写检查器。首先，你需要安装 [sphinxcontrib-spelling](https://pypi.org/project/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/`。

## 书写格式

在提及假设的人时，例如 "一个带有会话 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 个字符宽换行，除非一个代码例子被分割成两行时可读性明显降低，或者有其他好的理由。
- 在编写和编辑文档时要记住的主要事情是，你能添加的更多语义化标记越多越好。因此：

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

  远远不如：

  ```rst
  Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
  ```

  这是因为 Sphinx 将为后者生成适当的链接，这对读者有很大帮助。

  你可以在目标前加一个 `~` （那是一个波浪号）来获得该路径的 “最后一点”。所以 ``:mod:`~django.contrib.auth`` 将显示一个标题为 “auth” 的链接。
- 所有 Python 代码块都应使用 [blacken-docs](https://pypi.org/project/blacken-docs/) 自动格式化工具进行格式化。如果已配置 `pre-commit`，它将自动运行此工具。
- 使用 [`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::`。尽量少使用这些方框。
- 使用这些标题样式：

  ```rst
  ===
  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 的文档定义了一些额外的描述单元：

- 配置：

  ```rst
  .. setting:: INSTALLED_APPS
  ```

  为了连接配置，请使用配置 `` :setting:`INSTALLED_APPS` ``。
- 模板标签：

  ```rst
  .. templatetag:: regroup
  ```

  为了链接，请使用 `` :ttag:`regroup` ``。
- 模板过滤器：

  ```rst
  .. templatefilter:: linebreaksbr
  ```

  为了链接，请使用 `` :tfilter:`linebreaksbr` `` 。
- 字段查找（例如 `Foo.objects.filter(bar__exact=whatever)`）：

  ```rst
  .. fieldlookup:: exact
  ```

  为了链接，请使用 `` :lookup:`exact` ``。
- `django-admin` 命令：

  ```rst
  .. django-admin:: migrate
  ```

  为了链接，请使用 `` :djadmin:`migrate` ``。
- django-admin\`命令行选项：

  ```rst
  .. django-admin-option:: --traceback
  ```

  为了链接，请使用 ``:option:`command_name --trackback`` （或者省略 `command_name`，用于所有命令共享的选项，如 `--verbosity`）。
- Trac 问题的链接（通常用于补丁发布说明）：

  ```rst
  :ticket:`12345`
  ```

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

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

```rst
use this command:

.. code-block:: console

    $ python manage.py shell
```

用这个替代：

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

```rst
.. 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` 注释：

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

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

## 一个例子

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

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

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

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

## 翻译文档

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

## `django-admin` 手册页面

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

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