We place high importance on the consistency and readability of documentation. After all, Django was created in a journalism environment! So we treat our documentation like we treat our code: we aim to improve it as often as possible.
一般来说，文档会在以下两种情况时更新：
本节介绍文档作者如何以最有用和最不容易出错的方式修改文档。
Though Django's documentation is intended to be read as HTML at https://docs.djangoproject.com/, we edit it as a collection of plain text files written in the reStructuredText markup language for maximum flexibility.
We work from the development version of the repository because it has the latest-and-greatest documentation, just as it has the latest-and-greatest code.
We also backport documentation fixes and improvements, at the discretion of the merger, to the last release branch. This is because it's advantageous to have the docs for the last release be up-to-date and correct (see 版本之间的差异).
Django 的文档使用 Sphinx 文档系统——基于 docutils。基本思想是将轻量格式话的纯文本转化为 HTML，PDF 或其它任意输出格式。
Sphinx includes a sphinx-build command for turning reStructuredText into
other formats, e.g., HTML and PDF. This command is configurable, but the Django
documentation includes a Makefile that provides a shorter make html
command.
文档被分为以下几个类别：
教程 通过几步手把手的教学帮助读者创建一个小玩意。
教程的目的是帮助读者尽可能早地实现一些有用的东西，以便给他们带来信心。
Explain the nature of the problem we're solving, so that the reader understands what we're trying to achieve. Don't feel that you need to begin with explanations of how things work - what matters is what the reader does, not what you explain. It can be helpful to refer back to what you've done and explain afterward.
主题指引 旨在在一个较高的层次介绍一个原则或主题。
链接至参考资料而不要重复它。使用示例时，不要不情愿解释对您而言非常基本的事物——它对别人而言可能需要解释。
提供背景信息有助于新人将主题和他们已知的东西联系起来。
Reference guides contain technical references for APIs. They describe the functioning of Django's internal machinery and instruct in its use.
让参考资料紧紧围绕着主题。假设读者已经理解了所涉及的基本概念，但需要知道或被提醒 Django 是如何做到的。
参考指南并不是进行一般性解释的地方。如果你发现自己在解释基本概念，你可能想把这些材料移到主题指南中。
操作指南 是带领读者完成关键科目步骤的方法。
在指南中最重要的是用户想要实现什么。一个指南应该始终以结果为导向，而不是专注于 Django 如何实现所讨论的内部细节。
这些指南比教程更高级，并假定有一些关于 Django 如何工作的知识。假设读者已经学习了教程，并且毫不犹豫地让读者回到相应的教程，而不是重复同样的材料。
If you'd like to start contributing to our docs, get the development version of Django from the source code repository (see 安装开发版本):
$ git clone https://github.com/django/django.git
...\> git clone https://github.com/django/django.git
If you're planning to submit these changes, you might find it useful to make a fork of the Django repository and clone this fork instead.
Create and activate a virtual environment, then install the dependencies:
$ python -m venv .venv
$ source .venv/bin/activate
$ python -m pip install -r docs/requirements.txt
We can build HTML output from the docs directory:
$ cd docs
$ make html
...\> cd docs
...\> make.bat html
Your locally-built documentation will be accessible at
_build/html/index.html and it can be viewed in any web browser, though it
will be themed differently than the documentation at
docs.djangoproject.com. This is OK! If
your changes look good on your local machine, they'll look good on the website.
The source files are .txt files located in the docs/ directory.
These files are written in the reStructuredText markup language. To learn the markup, see the reStructuredText reference.
To edit this page, for example, we would edit the file
docs/internals/contributing/writing-documentation.txt and rebuild the
HTML with make 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. 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. Output is printed to the terminal, but can also be found in
_build/linkcheck/output.txt and _build/linkcheck/output.json.
Entries that have a status of "working" are fine, those that are "unchecked" or "ignored" have been skipped because they either cannot be checked or have matched ignore rules in the configuration.
Entries that have a status of "broken" need to be fixed. Those that have a
status of "redirected" may need to be updated to point to the canonical
location, e.g. the scheme has changed http:// → https://. In certain
cases, we do not want to update a "redirected" link, e.g. a rewrite to always
point to the latest or stable version of the documentation, e.g. /en/stable/ →
/en/3.2/.
When using pronouns in reference to a hypothetical person, such as "a user with a session cookie", gender-neutral pronouns (they/their/them) should be used. Instead of:
尽量避免使用将任务或操作的难度降到最低的词语，如 “easily”、“simply”、“just”、“merely”、“straightforward” 等等。人们的经验可能与你的期望不符，当他们发现某个步骤并不像暗示的那样 “straightforward” 或 “simple” 时，可能会感到沮丧。
以下是整个文档中常用术语的一些格式指南：
这些准则规定了我们的 reST（reStructuredText）文档格式：
在部分标题中，仅将首字母和专有名词大写。
将文档以 80 个字符宽换行，除非一个代码例子被分割成两行时可读性明显降低，或者有其他好的理由。
The main thing to keep in mind as you write and edit docs is that the more semantic markup you can add the better. So:
Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
Isn't nearly as helpful as:
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::。尽量少使用这些方框。
Use these heading styles:
===
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:: 来定义一个对该环境变量的文档的引用。
All Python code blocks in the Django documentation were reformatted with blacken-docs.
除了 Sphinx 的内置标记，Django 的文档定义了一些额外的描述单元：
Settings:
.. setting:: INSTALLED_APPS
为了连接配置，请使用配置 :setting:`INSTALLED_APPS`。
Template tags:
.. templatetag:: regroup
为了链接，请使用 :ttag:`regroup`。
Template filters:
.. templatefilter:: linebreaksbr
为了链接，请使用 :tfilter:`linebreaksbr` 。
Field lookups (i.e. Foo.objects.filter(bar__exact=whatever)):
.. fieldlookup:: exact
为了链接，请使用 :lookup:`exact`。
django-admin commands:
.. django-admin:: migrate
为了链接，请使用 :djadmin:`migrate`。
django-admin command-line options:
.. django-admin-option:: --traceback
为了链接，请使用 :option:`command_name --trackback （或者省略 command_name，用于所有命令共享的选项，如 --verbosity）。
Links to Trac tickets (typically reserved for patch release notes):
:ticket:`12345`
Django 的文档使用一个自定义的 console 指令，用于记录涉及 django-admin、manage.py、python 等的命令行实例。在 HTML 文档中，它渲染了一个双选项卡 UI，其中一个选项卡显示 Unix 风格的命令提示符，第二个选项卡显示 Windows 提示符。
For example, you can replace this fragment:
use this command:
.. code-block:: console
$ python manage.py shell
with this one:
use this command:
.. console::
$ python manage.py shell
请注意两件事：
.. code-block:: console 指令。'$' 提示符号，'/' 作为文件系统路径组件分隔符等等）。上面的例子将呈现一个有两个选项卡的代码示例块。第一个将显示：
$ python manage.py shell
与 .. code-block:: console 所呈现的内容相比没有变化）。
第二个将显示：
...\> py manage.py shell
我们对新功能的政策是：
All documentation of new features should be written in a way that clearly designates the features that are only available in the Django development version. Assume documentation readers are using the latest release, not the development version.
我们首选的标记新特性的方法是在特性的文档前加上。".. versionadded:: X.Y"，后面是一个强制性的空行和一个可选的描述（缩进）。
General improvements or other changes to the APIs that should be emphasized
should use the ".. versionchanged:: X.Y" directive (with the same format
as the versionadded mentioned above.
These versionadded and versionchanged blocks should be "self-contained."
In other words, since we only keep these annotations around for two releases,
it's nice to be able to remove the annotation and its contents without having
to reflow, reindent, or edit the surrounding text. For example, instead of
putting the entire description of a new or changed feature in a block, do
something like this:
.. 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"。
If a function, attribute, etc. is added, it's also okay to use a
versionadded annotation like this:
.. 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"`
This is based on OptiPNG version 0.7.5. Older versions may complain about the
-strip all option being lossy.
有关如何将它们组合在一起的快速示例，请考虑以下假设示例：
首先， 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>`.
We use the Sphinx doc cross-reference element when we want to
link to another document as a whole and the ref element when
we want to link to an arbitrary location in a document.
接下来，请注意配置的注解方式：
.. 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。
12月 05, 2023