我们高度重视文档的一致性和可读性。毕竟，Django是在新闻环境中创造出来的！因此，我们对待文档就像对待代码一样：我们的目标是尽可能经常地改进它。
文档更改通常有两种形式：
一般性的改进：打字错误更正、错误修复和通过更清晰的文字和更多的例子更好的解释。
新特性：自上次发布以来已添加到框架中的特性的文档。
本节解释了作者如何以最有用和最不易出错的方式来处理文档更改。
虽然Django的文档打算在https://docs.djangoproject.com/，上读为HTML语言，但为了实现最大的灵活性，我们将其编辑为用reStrucredText标记语言编写的纯文本文件的集合。
我们从资源库的开发版本开始工作，因为它有最新最好的文档，就像它有最新最好的代码一样。
我们还根据合并的自由裁量权，将文档修复和改进提交给最后一个发布分支。这是因为让最新版本的文档保持最新和正确是有利的(请参见 版本之间的差异 )。
Django的文档使用 Sphinx 文档系统，反过来又是基于 docutils. 其基本思想是将格式简单的纯文本文档转换为HTML、PDF和任何其他输出格式。
Sphinx包括一个 sphinx-build 用于将reStrufredText转换为其他格式(例如，HTML和PDF)的命令。该命令是可配置的，但Django文档包括一个 Makefile 这提供了一种更短的 make html 指挥部。
文件分为几个类别：
Tutorials 通过一系列的步骤，用手带着读者去创造一些东西。
教程中的重要内容是帮助读者完成一些有用的事情，最好尽早完成，以便给他们信心。
解释我们正在解决的问题的性质，以便读者理解我们试图实现的目标。不要觉得你需要从解释事物如何运作开始--重要的是读者做了什么，而不是你解释了什么。回顾你做过的事情并在事后解释会很有帮助。
Topic guides 目的在相当高的层次上解释一个概念或主题。
链接到参考资料，而不是重复它。使用例子，不要勉强解释那些对你来说很基本的事情——这可能是别人需要的解释。
提供背景上下文有助于新来者将主题与他们已经知道的内容联系起来。
Reference guides 包含API的技术参考。他们描述了姜戈内部机制的运作，并指导其使用。
将参考资料紧紧地集中在主题上。假设读者已经理解了所涉及的基本概念，但需要知道或被提醒Django是如何做到的。
参考指南不是一般解释的地方。如果你发现自己在解释基本概念，你可能会想把这些材料转移到主题指南中。
How-to guides 是引导读者完成关键主题步骤的方法。
操作指南中最重要的是用户想要实现什么。如何做应该始终以结果为导向，而不是专注于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 目录：
$ cd docs
$ make html
...\> cd docs
...\> make.bat html
您可以在以下位置访问本地构建的文档 _build/html/index.html 它可以在任何Web浏览器中查看，尽管它的主题与 docs.djangoproject.com 。这样就可以了！如果您的更改在本地计算机上看起来很好，它们在网站上也会看起来很好。
源文件是 .txt 文件位于 docs/ 目录。
这些文件是用reStrufredText标记语言编写的。要了解标记，请参阅 reStructuredText reference 。
例如，要编辑此页面，我们将编辑文件 docs/internals/contributing/writing-documentation.txt 并使用以下内容重新构建HTML make html 。
在提交文档之前，最好运行拼写检查器。您将需要安装 sphinxcontrib-spelling 第一。然后从 docs 目录，运行 make spelling 。错误的单词(如果有)以及出现错误的文件和行号将保存到 _build/spelling/output.txt 。
如果遇到误报（实际正确的错误输出），请执行以下操作之一：
用双重音(``)括起内联代码或品牌/技术名称。
查找拼写检查器识别的同义词。
如果，而且只有当，你确信你所用的词是正确的-将它添加到 docs/spelling_wordlist （请按字母顺序排列）。
文档中的链接可能会断开或更改，从而不再是规范链接。Sphinx提供了一个构建器，可以检查文档中的链接是否正常工作。从 docs 目录，运行 make linkcheck 。输出被打印到终端，但也可以在 _build/linkcheck/output.txt 和 _build/linkcheck/output.json 。
状态为“Working”的条目没有问题，那些“未选中”或“已忽略”的条目已被跳过，因为它们要么无法选中，要么与配置中的忽略规则匹配。
需要修复状态为“已损坏”的条目。可能需要更新那些状态为“已重定向”的文件，以指向规范位置，例如方案已更改 http:// → https:// 。在某些情况下，我们不希望更新“重定向”链接，例如，重写以始终指向文档的最新或稳定版本，例如 /en/stable/ → /en/3.2/ 。
当使用代词来指代一个假想的人时，例如“一个拥有会话cookie的用户”，应该使用中性代词(They/Thees/Them)。不是：
他或她…用它们。
他或她…使用它们。
他或她…使用它们。
他或她的…用他们的。
他自己…使用自己。
尽量避免使用将任务或操作中涉及的难度降至最低的词语，如“轻松”、“简单”、“公正”、“仅仅”、“直接”等等。人们的经验可能与你的期望不符，当他们找不到一个隐含的“直接”或“简单”的步骤时，他们可能会感到沮丧。
以下是有关文档中常用术语的一些样式指南：
** Django ** --提及框架时，将Django大写。它只有在python代码和djangoproject.com标识中是小写的。
电子邮件 ——连连字符都没有。
HTTP --预期发音为“Aitch Tee Tee Pee”，因此应以“an”开头，而不是“a”。
MySQL ， 《PostgreSQL》 ， SQLite
SQL --在引用SQL时，预期的发音应该是“ESS queue ell”，而不是“sequel”。因此，在“返回SQL表达式”这样的短语中，“SQL”前面应该是“an”，而不是“a”。
Python --当提到语言时，将python大写。
实现 ， 定制 ， 初始化 等等——使用美国的“ize”后缀，而不是“ise”。
子类 --它是一个没有连字符的单字，既作为动词（“该模型的子类”）也作为名词（“创建子类”）。
the web ， web framework --它没有大写。
网站 --用一个词，不要大写。
模型 --它不是大写的。
模板 --它不是大写的。
URLconf --使用三个大写字母，在“conf”之前没有空格。
view --它不是大写的。
这些指南规范了我们的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:: .
此外 Sphinx's built-in markup ，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-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 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>`.
我们用狮身人面像 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 '.
这就是所有事物的基本组合。
见 Localizing the Django documentation 如果您想帮助将文档翻译成另一种语言。
django-admin 人页¶Sphinx可以为 django-admin 命令。此配置在 docs/conf.py . 与其他文档输出不同，此手册页应包含在Django存储库中，并且版本如下 docs/man/django-admin.1 . 在更新文档时不需要更新此文件，因为它在发布过程中只更新一次。
要生成手册页的更新版本，请运行 make man 在 docs 目录。新的手册页将被写入 docs/_build/man/django-admin.1 .
12月 18, 2023