编写文档¶

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

文档更改通常有两种形式：

一般改进：通过更清晰的写作和更多的例子，更正错误，错误修复和更好的解释。
新功能：自上一版本以来已添加到框架的功能的文档。

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

获取原始文档¶

虽然Django的文档旨在在 https://docs.djangoproject.com/ 中作为HTML读取，我们将其编辑为一个文本文件的集合，以获得最大的灵活性。这些文件位于Django发行版的顶级 docs/ 目录中。

如果你想开始贡献我们的文档，从源代码仓库（见安装开发版本）获得Django的开发版本。开发版本有最新，最伟大的文档，就像它有最新和最伟大的代码。我们还根据提交者的判断，将文档修复和改进退回到最后一个发布分支。这是因为最后一个版本的文档是最新的和正确的（见版本之间的差异）是非常有利的。

开始使用Sphinx¶

Django的文档使用 Sphinx 文档系统，后者又基于 docutils。基本思想是将轻度格式化的纯文本文档转换为HTML，PDF和任何其他输出格式。

要在本地实际构建文档，您目前需要安装Sphinx - pip install Sphinx 应该做的伎俩。

然后，构建HTML很容易；只是从 docs 目录中的 make html （或Windows上的 make.bat html）。

要开始贡献，你需要阅读 reStructuredText Primer。之后，您将需要阅读有关用于管理元数据，索引和交叉引用的 Sphinx特定标记。

如何组织文档¶

文档分为以下几类：

教程带领读者通过一系列的步骤创造的东西。

教程中的重要事情是帮助读者实现有用的，最好是尽早，以给他们信心。

解释我们正在解决的问题的性质，以便读者了解我们正在努力实现的目标。不要觉得你需要开始解释事情如何工作 - 重要的是读者做什么，而不是你解释。回顾你以前做过的事情和解释是有帮助的。
主题指南旨在以相当高的水平解释一个概念或主题。

链接到参考材料，而不是重复。使用例子，不要勉强解释似乎对你非常基本的东西 - 这可能是别人需要的解释。

提供后台上下文帮助新手将主题连接到他们已经知道的东西。
参考指南包含API的技术参考。他们描述Django的内部机制的功能，并指导其使用。

保持参考材料紧紧关注主题。假设读者已经理解了所涉及的基本概念，但需要知道或者提醒Django是如何做到的。

参考指南不是一般解释的地方。如果你发现自己解释了基本概念，你可能想将该材料移动到主题指南。
如何指导是让读者通过关键主题的步骤的食谱。

在操作指南中最重要的是用户想要实现的。一个how-to应该总是以结果为导向，而不是关注Django如何实现任何正在讨论的内部细节。

这些指南比教程更先进，并假设一些关于Django如何工作的知识。假设读者遵循教程，并且毫不犹豫地将读者引回到适当的教程，而不是重复相同的材料。

写作风格¶

当使用关于假设人的代词（例如“具有会话cookie的用户”）时，应当使用性别中性代词（他们/他们的/他们）。代替：

他或她...使用他们。
他或她...使用他们。
他或她...使用他们。
他或她...使用他们的。
他或她自己...使用自己。

常用术语¶

以下是整个文档中常用术语的一些样式指南：

Django - 当引用框架时，使用Django。它只有在Python代码和djangoproject.com标志中的小写。
电子邮件 - 无连字符。
MySQL，PostgreSQL，SQLite
SQL - 当提及SQL时，预期的发音应该是“Ess Queue Ell”而不是“sequel”。因此，在像“返回SQL表达式”这样的短语中，“SQL”应该以“an”开头，而不是“a”。
蟒蛇 - 当提到的语言，大写Python。
实现，定制，初始化 等 - 使用美国的“ize”后缀，而不是“ise”。
子类 - 它是一个没有连字符的单词，既作为动词（“子类的模型”）和作为名词（“创建子类”）。
Web，万维网，网络 - 注意当提及万维网时，Web总是大写。
网站 - 使用一个字，没有大写。

Django特定术语¶

模型 - 它不大写。
模板 - 它不大写。
URLconf - 使用三个大写字母，在“conf”前没有空格。
视图 - 它不大写。

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 将强制突出显示，尽管语法无效。

使用这些标题样式:

===
One
===

Two
===

Three
-----

Four
~~~~

Five
^^^^

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（通常保留为补丁发行说明）:
```
:ticket:`12345`
```

记录新功能¶

我们的新功能政策是：

新功能的所有文档都应该以明确指定功能的方式编写，这些功能仅在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`。

这基本上是一切如何配合在一起。

拼写检查¶

在提交文档之前，最好运行拼写检查器。您需要先安装几个软件包：

发烧剂（需要附魔）
sphinxcontrib-spelling

然后从 docs 目录运行 make spelling。错误的单词（如果有）以及出现的文件和行号将保存到 _build/spelling/output.txt。

如果遇到假阳性（错误输出实际上是正确的），请执行以下操作之一：

环绕内嵌代码或具有严重口音（`）的品牌/技术名称。
查找拼写检查程序可识别的同义词。
如果，而且只有当你确定你使用的词是正确的 - 添加到 docs/spelling_wordlist （请按字母顺序保持列表）。

翻译文档¶

如果您想帮助将文档翻译成另一种语言，请参阅本地化Django文档。

`django-admin` 手册页¶

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

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