编写文档¶
我们非常重视文档的一致性和可读性。毕竟,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标志中的小写。
电子邮件 - 无连字符。
MySQL,PostgreSQL,SQLite
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
格式相同。
这些 versionadded
和 versionchanged
块应该是“自包含”的。换句话说,由于我们只为两个版本保留这些注释,因此能够删除注释及其内容而不必重排,重新压缩或编辑周围文本是很好的。例如,不是把一个新的或改变的特性的整个描述放在一个块中,做这样的事情:
.. 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.
将更改的注释注释放在部分的底部,而不是顶部。
另外,避免在 versionadded
或 versionchanged
块之外引用特定版本的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
编写。