Writing documentation

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

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

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

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

Getting the raw documentation

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

如果您想开始贡献我们的文档,请从源代码存储库获取Django的开发版本(请参阅Installing the development version)。 开发版本有最新,最伟大的文档,就像它有最新和最伟大的代码。 我们还根据提交者的判断,将文档修订和改进退回到最后一个发布分支。 这是因为最后一个版本的文档是最新和正确的(参见Differences between versions之间的差异)是非常有利的。

Getting started with Sphinx

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

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

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

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

您的本地制作的文档将与docs.djangoproject.com上的文档不同。 还行吧! 如果您的本地机器的更改看起来不错,那么网站上看起来会很好。

文件的组织方式

文档分为几类:

  • Tutorials通过一系列步骤让读者轻松创作。

    教程中的重要内容是帮助读者尽可能早地获得有用的东西,以便让他们有信心。

    解释我们正在解决的问题的本质,让读者了解我们正在实现的目标。 不要以为你需要开始解释事情如何运作 - 重要的是读者所做的,而不是你所解释的。 参考你以后做的和解释后可能是有帮助的。

  • Topic guides旨在以相当高的水平解释一个概念或主题。

    链接到参考资料,而不是重复。 使用示例,不要不情愿地解释对您看起来非常基本的东西 - 这可能是别人需要的解释。

    提供背景上下文帮助新人将主题与他们已经知道的内容相连接。

  • Reference guides包含API的技术参考。 他们描述了Django内部机械的功能并指示使用。

    保持参考资料紧紧关注主题。 假设读者已经了解了所涉及的基本概念,但需要知道或提醒Django如何做。

    参考指南不是一般解释的地方。 如果您发现自己解释基本概念,您可能希望将该材料移动到主题指南。

  • How-to guides是通过读者阅读关键主题中的步骤的食谱。

    用户想要实现的方式指导中最重要的是什么。 一个操作方法应该始终以结果为导向,而不是专注于Django如何实现正在讨论的内部细节。

    这些指南比教程更先进,并且介绍一些关于Django如何工作的知识。 假设读者已经遵循教程,不要犹豫,将阅读器回到适当的教程,而不是重复相同的材料。

写作风格

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

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

常用术语

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

  • Django - 当引用框架时,大小写Django。 它只有在Python代码和djangoproject.com标志中的小写。
  • 电子邮件 - 无连字符。
  • MySQLPostgreSQLSQLite
  • SQL - 在引用SQL时,预期的发音应为“Ess Queue Ell”而不是“sequel”。 因此,在像“返回SQL表达式”这样的短语中,“SQL”应该以“an”开头,而不是“a”。
  • Python - 在引用语言时,使用Python。
  • 实现自定义初始化等。 - 使用美国“ize”后缀,而不是“ise”。
  • 子类 - 它是没有连字符的单个单词,既作为动词(“子类的模型”)和作为名词(“创建子类”)。
  • 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将为后者生成适当的链接,这极大地有助于读者。

    您可以使用~(这是一个波浪号)来为目标前缀,以获得该路径的“最后一位”。 所以:mod:`~django.contrib.auth`将只显示一个标题为“auth”的链接。

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

  • .. 代码块:: <lang> 到文字块,以便它们被突出显示。 喜欢依靠自动突出显示使用简单 :: (两个冒号)。 这有一个好处,如果代码包含一些无效的语法,它不会被突出显示。 添加 .. 代码块:: 蟒蛇例如,尽管语法无效,它将强制突出显示。

  • 使用这些标题样式:

    ===
    One
    ===
    
    Two
    ===
    
    Three
    -----
    
    Four
    ~~~~
    
    Five
    ^^^^
    

Django-specific markup

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

    要链接,请使用:选项:`command_name - traceback`(或省略command_name所有命令,如--verbosity)。

  • 链接到Trac门票(通常保留补丁发行说明):

    :ticket:`12345`
    

Documenting new features

我们的新功能政策是:

新功能的所有文档都应该以明确的方式编写,这些功能仅在Django开发版本中可用。 假设文档读者正在使用最新版本,而不是开发版本。

标记新功能的首选方法是将功能文档放在以下位置:“.. versionadded :: X.Y“,后跟一个强制性空行和可选描述(缩进)。

应强调的一般改进或其他更改应使用“.. 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 所有选项是有损的。

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 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`来引用它。

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

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中写入。