编写文档

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.

一般来说,文档会在以下两种情况时更新:

  • 一般改进:通过更清晰的书写和更多示例,更正、修复文档错误,更好的解释功能。
  • 新特性:自上一个版本发布后,添加到框架中的功能文档。

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

The Django documentation process

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 如何工作的知识。假设读者已经学习了教程,并且毫不犹豫地让读者回到相应的教程,而不是重复同样的材料。

How to start contributing documentation

Clone the Django repository to your local machine

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.

Set up a virtual environment and install dependencies

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

Build the documentation locally

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.

Making edits to the documentation

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.

如果你遇到假阳性的情况(错误输出实际上是正确的),请采取以下措施之一:

  • Surround inline code or brand/technology names with double grave accents (``).
  • 查找拼写检查程序发现的同义词。
  • 如果,只是如果,你确定你的单词拼写是正确的——将其加入 docs/spelling_wordlist (请保持这个列表以字母顺序排列)。

书写格式

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:

  • 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 -- the expected pronunciation is "Aitch Tee Tee Pee" and therefore should be preceded by "an" and not "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 -- it's not capitalized.
  • website -- 用一个单词表示,不大写。

Django 专用术语

  • model -- 它不是大写的。
  • template -- 它不是大写的。
  • URLconf -- 使用了三个大写字母,在 “conf” 之前没有空格。
  • view -- 它不是大写的。

reStructuredText 文件语法指南

这些准则规定了我们的 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:: 来定义一个对该环境变量的文档的引用。

Changed in Django 4.2:

All Python code blocks in the Django documentation were reformatted with blacken-docs.

Django 特有的标记

除了 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-adminmanage.pypython 等的命令行实例。在 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 指令。
  • 你不需要改变代码例子的实际内容。你仍然假设 Unix-y 环境来编写它(即一个 '$' 提示符号,'/' 作为文件系统路径组件分隔符等等)。

上面的例子将呈现一个有两个选项卡的代码示例块。第一个将显示:

$ 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.

把修改后的注解说明放在一个章节的底部,而不是顶部。

另外,避免在 versionaddedversionchanged 块之外提及 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