编写文档

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

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

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

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

获取原始文档

尽管Django的文档打算在https://docs.djangoproject.com/上被读作HTML,但我们将它编辑为文本文件的集合,以获得最大的灵活性。 这些文件位于Django版本的顶级docs/目录中。

如果您想开始贡献我们的文档,请从源代码库获取开发版本的Django(请参阅Installing the development version)。 开发版本具有最新和最好的文档,就像它拥有最新和最好的代码一样。 我们还将提交者自行决定的文档修复和改进支持到最后的发行版分支。 这是因为最新版本的文档是最新的和正确的(参见Differences between versions)是非常有利的。

开始使用Sphinx

Django’s documentation uses the Sphinx documentation system, which in turn is based on docutils. 其基本思想是将格式简明的纯文本文档转换为HTML,PDF和任何其他输出格式。

为了在本地生成文档,你需要安装Sphinx - pip install Sphinx招。

Then, building the HTML is easy; just make html (or make.bat html on Windows) from the docs directory.

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

您在本地构建的文档将与docs.djangoproject.com中的文档不同。 还行吧! 如果你的改变在你的本地机器上看起来不错,他们在网站上看起来不错。

文档如何组织

文档分为几类:

  • Tutorials通过一系列的步骤创造一些东西的读者。

    教程中最重要的事情就是帮助读者尽可能早地实现一些有用的东西,以便给予他们信心。

    解释我们正在解决的问题的性质,以便读者理解我们要实现的目标。 不要觉得你需要从解释事物的工作开始 - 重要的是读者所做的,而不是你所解释的。 回顾一下你所做的事情并在之后解释会有帮助。

  • Topic guides aim to explain a concept or subject at a fairly high level.

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

    提供背景环境有助于新手将主题与他们已知的事物联系起来。

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

    保持参考资料紧紧围绕这个问题。 假设读者已经理解了所涉及的基本概念,但是需要知道或者提醒Django如何去做。

    参考指南不是一般性解释的地方。 如果您发现自己解释基本概念,则可能需要将该材料移至主题指南。

  • How-to guides are recipes that take the reader through steps in key subjects.

    在使用指南中最重要的是用户想要达到的目标。 一个方法应该总是以结果为导向,而不是集中于Django如何实现正在讨论的内容的内部细节。

    这些指南比教程更先进,并假设了一些关于Django如何工作的知识。 假设读者已经按照教程,并毫不犹豫地提请读者回到适当的教程,而不是重复相同的材料。

写作风格

当使用代词来引用一个假设的人时,比如“有会话cookie的用户”,应该使用性别中性代词(他们/他们/他们)。 代替:

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

常用术语

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

  • Django – when referring to the framework, capitalize Django. 它仅在Python代码中和djangoproject.com徽标中为小写。
  • 电子邮件 - 没有连字符。
  • MySQLPostgreSQLSQLite
  • SQL – when referring to SQL, the expected pronunciation should be “Ess Queue Ell” and not “sequel”. 因此,在诸如“返回SQL表达式”之类的短语中,“SQL”应该以“an”而不是“a”开头。
  • Python – when referring to the language, capitalize Python.
  • 实现自定义初始化等 - 使用美国的“ize”后缀,而不是“ise”。
  • 子类 - 它是一个没有连字符的单个词,既作为动词(“子类模型”)也作为名词(“创建子类”)。
  • Web, World Wide Web, the Web – note Web is always capitalized when referring to the World Wide Web.
  • 网站 - 使用一个词,没有大写。

Django特有的术语

  • 模型 - 不是大写。
  • 模板 - 没有大写。
  • URLconf – use three capitalized letters, with no space before “conf.”
  • 视图 - 没有大写。

reStructuredText文件准则

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

  • 在章节标题中,只用首字母和专有名词。

  • 将文档封装在80个字符范围内,除非代码示例在分成两行时的可读性明显降低,或者出于其他原因。

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

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

    几乎不像以下那样有帮助:

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

    这是因为狮身人面像将为后者生成适当的链接,这大大帮助读者。

    你可以在目标前添加一个~(这是一个代字号)来得到该路径的“最后一位”。 所以:mod:`~django.contrib.auth`只显示一个标题为“auth”的链接。

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

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

  • 使用这些标题样式:

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

特定于Django的标记

除了Sphinx built-in markup之外,Django的文档还定义了一些额外的描述单元:

  • 设置:

    .. setting:: INSTALLED_APPS
    

    要链接到设置,请使用:setting:`INSTALLED_APPS`

  • 模板标签:

    .. templatetag:: regroup
    

    要链接,请使用:ttag:`regroup`

  • 模板过滤器:

    .. templatefilter:: linebreaksbr
    

    要链接,请使用:tfilter:`linebreaksbr`

  • Field lookups (i.e. Foo.objects.filter(bar__exact=whatever)):

    .. fieldlookup:: exact
    

    要链接,请使用:lookup:`exact`

  • django-admin命令:

    .. django-admin:: migrate
    

    要链接,请使用:djadmin:`migrate`

  • django-admin command-line options:

    .. django-admin-option:: --traceback
    

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

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

    :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。 即使在一个块中,这样做通常也是多余的,因为这些注释分别呈现为“Django A.B中的新增内容”和“DjangoA.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设置的“规范”目标。 This means any time I talk about ADMINS, I can reference it using :setting:`ADMINS`.

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

拼写检查

在提交文档之前,运行拼写检查器是个好主意。 你需要先安装一些包:

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

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

  • 环绕内嵌代码或品牌/技术名称与重音(`)。
  • 查找拼写检查器识别的同义词。
  • If, and only if, you are sure the word you are using is correct - add it to docs/spelling_wordlist (please keep the list in alphabetical order).

翻译文档

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

django-admin手册页

狮身人面像可以为django-admin命令生成一个手册页。 这是在docs/conf.py中配置的。 与其他文档输出不同的是,这个手册页应该包含在Django仓库和版本中,如docs/man/django-admin.1 在更新文档时不需要更新这个文件,因为它在发布过程中被更新了一次。

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