编写文档¶

Django 文档流程¶

虽然 Django 的文档旨在以 HTML 格式在 https://docs.django.ac.cn/ 上阅读，但为了获得最大的灵活性，我们将其作为使用 reStructuredText 标记语言编写的纯文本文件集合进行编辑。

我们基于开发版本的仓库进行工作，因为它拥有最新、最好的文档，正如它拥有最新、最好的代码一样。

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

Django 的文档使用 Sphinx 文档系统，该系统反过来基于 docutils。其基本思想是将轻量级格式化的纯文本文档转换为 HTML、PDF 和任何其他输出格式。

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

文档的组织方式¶

文档分为几个类别

• 教程 引导读者通过一系列步骤来完成某项工作。

  教程的重点是帮助读者完成一些有用的事情，最好越快越好，以给予他们信心。

  解释我们正在解决的问题的本质，以便读者理解我们想要实现的目标。不要觉得你需要从解释事物如何工作开始——重要的是读者做了什么，而不是你解释了什么。事后回顾所做的事情并进行解释是有帮助的。

• 主题指南 旨在在相当高的层面上解释概念或主题。

  链接到参考资料，而不是重复它。使用示例，不要吝于解释对你来说似乎非常基础的事情——这可能正是别人需要的解释。

  提供背景语境有助于新手将该主题与他们已经了解的事物联系起来。

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

  保持参考资料紧扣主题。假设读者已经了解所涉及的基本概念，但需要知道或被提醒 Django 是如何实现它的。

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

• 操作指南 是引导读者完成关键主题步骤的配方。

  操作指南中最重要的内容是用户想要实现的目标。操作指南应始终以结果为导向，而不是专注于 Django 如何实现所讨论内容的内部细节。

  这些指南比教程更高级，并假设读者对 Django 的工作原理有所了解。假设读者已经学习了教程，并且不要犹豫，将读者指引回适当的教程，而不是重复相同的内容。

如何开始贡献文档¶

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

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

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

$ cd docs
$ make html

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

$ make check

...\> make.bat check

$ make spelling

...\> make.bat spelling

$ make black

...\> make.bat black

$ make lint

...\> make.bat lint

$ make linkcheck

...\> make.bat linkcheck

写作风格¶

当使用代词指代假想的人时，例如“带有会话 cookie 的用户”，应使用性别中立的代词（they/their/them）。代替

• he or she… 使用 they。

• him or her… 使用 them。

• his or her… 使用 their。

• his or hers… 使用 theirs。

• himself or 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 – 指代该语言时，大写 Python。

• realize, customize, initialize 等 – 使用美式“ize”后缀，而不是“ise”。

• subclass – 是一个单词，没有连字符，既作为动词（“subclass that model”），也作为名词（“create a 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”的链接。

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

• 使用 :cve: 来引用常见漏洞和披露 (CVE) 标识符。例如，使用 :cve:`2019-14232`。

• 在使用 Sphinx 指令（如 .. class::、.. method:: 和 .. attribute::）记录 Python 对象（类、方法、属性等）时，所有内容必须正确缩进，以确保正确的渲染并支持诸如自动目录生成等功能。

  遵循这些规则

  • 指令本身应保持与左侧边距齐平（无缩进）。

  • 指令下的所有描述性文本必须缩进 4 个空格。

  • 多行描述必须保持相同的缩进级别。

  • 嵌套指令（例如，类中的方法）需要额外的 4 个空格缩进以保持层次结构。

  • 字段列表（例如 :param:, :returns: 等）必须与指令的内容级别对齐。

  示例：

  .. class:: MyClass
  
      A brief description of the class.
  
      .. method:: my_method(arg1, arg2)
  
          Method description.
  
          :param arg1: Description of the first parameter
          :param arg2: Description of the second parameter
  
      .. attribute:: my_attribute
  
          Attribute description.
  

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 --traceback`（或省略 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 环境编写它（即一个 '$' 提示符号，'/' 作为文件系统路径组件分隔符等）

上面的示例将呈现一个带有两个标签的代码示例块。第一个将显示

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

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

  这会将以下标题标记为设置 ADMINS 的“权威”目标。这意味着任何时候我谈论 ADMINS 时，我都可以使用 :setting:`ADMINS` 来引用它。

这基本上就是一切如何组合在一起的。

翻译文档¶

如果你想帮助将文档翻译成其他语言，请参阅 本地化 Django 文档。

django-admin 手册页¶

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

要生成手册页的更新版本，请在 docs 目录中运行

$ make man

...\> make.bat man

新的手册页将写入 docs/_build/man/django-admin.1。