Django 文档流程¶

虽然 Django 的文档旨在在 https://docs.django.ac.cn/ 以 HTML 形式阅读，但为了最大限度地提高灵活性，我们将其编辑为用 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

写作风格¶

当使用代词指代假设的人（例如“具有会话cookie的用户”）时，应使用中性代词（ta/ta的/ta们）。不要使用

• 他或她…… 使用ta。

• 他或她…… 使用ta们。

• 他的或她的…… 使用ta们的。

• 他的或她的…… 使用ta们的。

• 使用“themselves” 代替“himself or herself”。

避免使用轻描淡写的词语来描述任务或操作的难度，例如“easily”（轻松地）、“simply”（简单地）、“just”（仅仅）、“merely”（仅仅）、“straightforward”（简单的）等等。用户的实际体验可能与你的预期不符，如果他们发现某个步骤并非像描述的那样“简单”或“直接”，可能会感到沮丧。

常用术语¶

以下是关于文档中常用术语的一些风格指南

• 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”的链接。

• 所有 Python 代码块都应使用 blacken-docs 自动格式化程序进行格式化。如果配置了 pre-commit，它将由 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 --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 的特定版本。即使在块内，这样做通常也是多余的，因为这些注释分别呈现为“Django A.B 中的新增功能”和“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。