Skip to main content

编写文档

我们非常重视文档的一致性和可读性。毕竟,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标志中的小写。

  • 电子邮件 - 无连字符。

  • MySQLPostgreSQLSQLite

  • 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 格式相同。

这些 versionaddedversionchanged 块应该是“自包含”的。换句话说,由于我们只为两个版本保留这些注释,因此能够删除注释及其内容而不必重排,重新压缩或编辑周围文本是很好的。例如,不是把一个新的或改变的特性的整个描述放在一个块中,做这样的事情:

.. 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”。

如果添加了一个函数,属性等,也可以使用像这样的 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`

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

拼写检查

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

然后从 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 编写。