编写文档

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

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

  • 一般改进：通过更清晰的书写和更多示例，更正、修复文档错误，更好的解释功能。

  • 新特性：自上一个版本发布后，添加到框架中的功能文档。

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

Django 文档编写流程

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

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

我们还会根据合并者的判断，将文档修复和改进内容反向移植到上一个发布分支。这是因为让上一个版本的文档保持最新和正确是有好处的（参见 版本之间的差异）。

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

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

文档是如何组成

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

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

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

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

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

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

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

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

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

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

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

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

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

如何开始贡献文档

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

如果你想开始为我们的文档做贡献，可以从源代码仓库获取 Django 的开发版本（参见：安装开发版本）：

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

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

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

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

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

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

在本地构建文档

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

$ cd docs
$ make html

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

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

对文档进行编辑

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

这些文件是用 reStructuredText 标记语言编写的。要了解这种标记语言，请参阅 reStructuredText 参考手册。

要编辑此页面，例如，我们会编辑文件 docs/internals/contributing/writing-documentation.txt，然后使用 make html 重新构建 HTML。

拼写检查

在提交文档之前，最好运行拼写检查器。首先，你需要安装 sphinxcontrib-spelling。然后从 docs 目录中运行 make spelling。错误的单词（如果有的话）以及它们出现的文件和行号将保存到 _build/spelling/output.txt。

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

  • 用双反引号（``）括起内联代码或品牌/技术名称。

  • 查找拼写检查程序发现的同义词。

  • 如果，只是如果，你确定你的单词拼写是正确的——将其加入 docs/spelling_wordlist （请保持这个列表以字母顺序排列）。

书写格式

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

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

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

    远远不如：

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

  • 使用这些标题样式：

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

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

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

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

一个例子

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

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

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

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

翻译文档

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

django-admin 手册页面

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

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

Back to Top