Writing documentation

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

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

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

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

Getting the raw documentation

虽然Django的文档旨在在https://docs.djangoproject.com/上以HTML形式阅读,但我们将其编辑为一个文本文件集合,以获得最大的灵活性。这些文件位于Django版本的顶层docs/目录中。

如果您想开始贡献我们的文档,请从源代码存储库获取Django的开发版本(请参阅Installing the development version)。开发版本有最新,最伟大的文档,就像它有最新和最伟大的代码。我们还根据提交者的判断,将文档修订和改进退回到最后一个发布分支。That’s because it’s highly advantageous to have the docs for the last release be up-to-date and correct (see Differences between versions).

Getting started with Sphinx

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

要在本地实际构建文档,您可以使用 - pip install Sphinx 安装Sphinx

注意

构建Django文档需要Sphinx 1.0.2或更高版本。Sphinx还需要Pygments库进行语法高亮;构建Django文档需要Pygments 1.1或更高版本(最新版本应该自动与Sphinx一起安装)。

然后,构建HTML很容易;只需make html(或make.bat html >在Windows上)从docs目录。

要开始投稿,您需要阅读reStructuredText Primer之后,您将要阅读有关用于管理元数据,索引和交叉引用的Sphinx-specific markup

写作风格

当使用关于假设的人(例如“具有会话cookie的用户”)的代词时,应该使用性别中性代词(他们/他们的/他们)。代替:

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

常用术语

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

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

Django-specific terminology

  • 模型 - 它不大写。
  • 模板 - 它不大写。
  • URLconf - 使用三个大写字母,在“conf”之前没有空格。
  • 查看 - 未大写。

Guidelines for reStructuredText files

这些准则规定了我们的reST(reStructuredText)文档的格式:

  • 在节标题中,只使用初始词和专有名词。

  • 将文档以80个字符宽度包装,除非代码示例在拆分为两行时显着降低可读性,或者另一个好的原因。

  • 在编写和编辑文档时,要记住的主要事情是,更多的语义标记你可以添加更好。所以:

    Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
    

    是不是几乎有用的:

    Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
    

    这是因为Sphinx将为后者生成适当的链接,这极大地有助于读者。您可以添加的有用标记的数量基本上没有限制。

  • 使用intersphinx引用Python和Sphinx的文档。

Django-specific markup

除了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
    

    要链接,请使用:djadminopt:`--traceback`

  • 指向Trac ticket的链接(通常保留用于较小发行说明):

    :ticket:`12345`
    

Documenting new features

我们的新功能政策是:

All documentation of new features should be written in a way that clearly designates the features are only available in the Django development version. Assume documentation readers are using the latest release, not the development version.

我们首选的标记新功能的方法是使用:.. versionadded :: XY t0 >“,后跟强制性空行和可选内容(缩进)。

需要强调的一般改进或API的其他更改应使用“.. versionchanged :: XY t0 >“指令(格式与上述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注释,

An example

有关如何一起适用的快速示例,请考虑此假设示例:

  • 首先,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 tuple)
    
    A tuple that lists 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 tuple 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`来引用它。

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

Improving the documentation

可以做一些小的改进,使文档读取和看起来更好:

  • 各种index.txt文档中的大多数文档具有非常短或甚至不存在的介绍文本。这些文档中的每一个都需要一个很好的简介,低于这一点的内容。

  • 词汇是非常敷衍的。它需要填写。

  • 添加更多元数据目标。很多地方看起来像:

    ``File.close()``
    ~~~~~~~~~~~~~~~~
    

    ...这些应该是:

    .. method:: File.close()
    

    也就是说,使用元数据而不是标题。

  • 添加更多链接 - 几乎所有内联代码字面量现在可能变成一个外部参照。

    请参阅_ext中的literals_to_xrefs.py文件 - 它是一个shell脚本,以帮助完成此项工作。

    这可能是一个持续,永无止境的项目。

  • 尽可能使用链接。因此,使用:setting:`ADMINS`而不是``ADMINS``

  • 在适当的地方使用指令。一些指令(例如.. setting ::)是前缀样式指令;他们在他们描述的单位之前去这些被称为“crossref”指令。其他(例如.. class ::)生成自己的标记;这些应该在他们描述的部分的内部。这些称为“描述单元”。

    您可以在_ext/djangodocs.py中查看哪些内容;它注册角色作为其中一个。

  • ... 代码块:: &lt; lang&gt;添加到文字块,

  • 当引用类/函数/模块等时,你需要使用目标的完全限定名(:class:`django.contrib.contenttypes.models.ContentType`)。

    因为这在输出中看起来不是很棒 - 它显示了对象的整个路径 - 你可以在目标前加上一个~(这是一个波浪号)来获得“最后一位”的路径。因此,:class:`~django.contrib.contenttypes.models.ContentType`将只显示一个标题为“ContentType”的链接。

Spelling check

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

然后,从docs目录运行make 拼写错误的单词(如果有)及其出现的文件和行号将保存到_build/spelling/output.txt

如果遇到假阳性(错误输出实际上是正确的),请执行以下操作之一:

  • 环绕内嵌代码或具有严重口音(`)的品牌/技术名称。
  • 查找拼写检查程序可识别的同义词。
  • 如果且仅当您确定您使用的字词是正确的,请将其添加到docs/spelling_wordlist(请按字母顺序保存列表)。

Translating documentation

如果您想帮助将文档翻译成其他语言,请参阅Localizing the Django documentation

django-admin man page

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

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