编写文档¶

我们非常重视文档的一致性和可读性。毕竟，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。

拼写检查¶

Before you commit your docs, it's a good idea to run the spelling checker. You'll need to install sphinxcontrib-spelling first. Then from the docs directory, run:

/ 

$ make spelling

...\> make.bat spelling

Wrong words (if any) along with the file and line number where they occur will be saved to _build/spelling/output.txt.

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

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

链接检查¶

Links in documentation can become broken or changed such that they are no longer the canonical link. Sphinx provides a builder that can check whether the links in the documentation are working. From the docs directory, run:

/ 

$ make linkcheck

...\> make.bat linkcheck

Output is printed to the terminal, but can also be found in _build/linkcheck/output.txt and _build/linkcheck/output.json.

Warning

The execution of the command requires an internet connection and takes several minutes to complete, because the command tests all the links that are found in the documentation.

状态为 "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 个字符宽换行，除非一个代码例子被分割成两行时可读性明显降低，或者有其他好的理由。
在编写和编辑文档时要记住的主要事情是，你能添加的更多语义化标记越多越好。因此：
```
Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
```
远远不如：
```
Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
```
这是因为 Sphinx 将为后者生成适当的链接，这对读者有很大帮助。

你可以在目标前加一个 ~ （那是一个波浪号）来获得该路径的 “最后一点”。所以 :mod:`~django.contrib.auth 将显示一个标题为 “auth” 的链接。
All Python code blocks should be formatted using the blacken-docs auto-formatter. This will be run by pre-commit if that is configured.
使用 intersphinx 来引用 Python 和 Sphinx 的文档。
在文字块中加入 .. code-block:: <lang>，使其得到高亮。更倾向于使用 :: （两个冒号）来自动突出显示。这样做的好处是，如果代码中包含一些无效的语法，它就不会被高亮显示。例如，添加 .. code-block:: python，就可以在无效的语法中强制高亮显示。
为了提高可读性，使用 .. admonition:: Descriptive title 而不是 .. note::。尽量少使用这些方框。

使用这些标题样式：

===
One
===

Two
===

Three
-----

Four
~~~~

Five
^^^^

Use :rfc: to reference a Request for Comments (RFC) and try to link to the relevant section if possible. For example, use :rfc:`2324#section-2.3.2` or :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:: 来定义一个对该环境变量的文档的引用。
Use :cve: to reference a Common Vulnerabilities and Exposures (CVE) identifier. For example, use :cve:`2019-14232`.

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

...\> 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。在更新文档时不需要更新这个文件，因为它作为发行过程的一部分被更新一次。

To generate an updated version of the man page, in the docs directory, run:

/ 

$ make man

...\> make.bat man

The new man page will be written in docs/_build/man/django-admin.1.

编写文档¶

Django 文档编写流程¶

文档是如何组成¶

如何开始贡献文档¶

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

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

在本地构建文档¶

对文档进行编辑¶

拼写检查¶

链接检查¶

书写格式¶

常用术语¶

Django 专用术语¶

reStructuredText 文件语法指南¶

Django 特有的标记¶

记录新功能¶

最小化图像¶

一个例子¶

翻译文档¶

`django-admin` 手册页面¶

Additional Information

Support Django!

Contents

Getting help

Download:

编写文档¶

Django 文档编写流程¶

文档是如何组成¶

如何开始贡献文档¶

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

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

在本地构建文档¶

对文档进行编辑¶

拼写检查¶

链接检查¶

书写格式¶

常用术语¶

Django 专用术语¶

reStructuredText 文件语法指南¶

Django 特有的标记¶

记录新功能¶

最小化图像¶

一个例子¶

翻译文档¶

django-admin 手册页面¶

Additional Information

Support Django!

Contents

Getting help

Download:

`django-admin` 手册页面¶