编写文档 — Django 文档

来自菜鸟教程
Django/docs/3.0.x/internals/contributing/writing-documentation
跳转至：导航、​搜索

编写文档

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

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

  • 总体改进：通过更清晰的文字和更多示例进行拼写更正、错误修复和更好的解释。
  • 新功能：自上次发布以来已添加到框架中的功能的文档。

本节解释了作者如何以最有用和最不容易出错的方式制作他们的文档更改。

获取原始文档

尽管 Django 的文档旨在在 https://docs.djangoproject.com/ 上以 HTML 形式阅读，但我们将其编辑为文本文件的集合以实现最大的灵活性。 这些文件位于 Django 版本的顶级 docs/ 目录中。

如果您想开始为我们的文档做出贡献，请从源代码存储库中获取 Django 的开发版本（请参阅 安装开发版本 ）。 开发版本拥有最新最好的文档，就像它拥有最新最好的代码一样。 我们还根据提交者的判断将文档修复和改进向后移植到最后一个发布分支。 这是因为让最新版本的文档保持最新和正确是非常有利的（请参阅 版本之间的差异 ）。


Sphinx 入门

Django 的文档使用 Sphinx 文档系统，该系统又基于 docutils。 基本思想是将格式较浅的纯文本文档转换为 HTML、PDF 和任何其他输出格式。

要在本地构建文档，请安装 Sphinx：

然后从 docs 目录构建 HTML：

要开始贡献，您需要阅读 reStructuredText 参考 。

您本地构建的文档的主题将与 docs.djangoproject.com 上的文档不同。 还行吧！ 如果您的更改在本地机器上看起来不错，那么它们在网站上也会看起来不错。


文档的组织方式

文档分为几类：

  • 教程 带领读者通过一系列步骤来创造一些东西。

    教程中的重要事情是帮助读者获得一些有用的东西，最好是尽早，以便给他们信心。

    解释我们正在解决的问题的性质，以便读者了解我们正在努力实现的目标。 不要觉得你需要从解释事物的运作方式开始——重要的是读者做了什么，而不是你解释了什么。 回顾您所做的事情并在事后进行解释可能会有所帮助。

  • 主题指南旨在在相当高的水平上解释一个概念或主题。

    链接到参考资料而不是重复。 使用例子，不要勉强解释对你来说看起来很基本的事情——这可能是其他人需要的解释。

    提供背景上下文有助于新手将主题与他们已经知道的事物联系起来。

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

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

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

  • 操作指南 是引导读者完成关键主题步骤的食谱。

    操作指南中最重要的是用户想要实现的目标。 how-to 应该始终以结果为导向，而不是专注于 Django 如何实现正在讨论的任何内容的内部细节。

    这些指南比教程更高级，并假设您对 Django 的工作方式有一些了解。 假设读者已经阅读了教程，并毫不犹豫地将读者推荐回适当的教程，而不是重复相同的材料。


写作风格

当使用代词指代假设的人时，例如“具有会话 cookie 的用户”，应使用中性代词（他们/他们/他们）。 代替：

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

尽量避免使用将任务或操作的难度降到最低的词语，例如“容易”、“简单”、“只是”、“仅仅”、“直截了当”等。 人们的体验可能与您的期望不符，当他们没有找到暗示的“直截了当”或“简单”的步骤时，他们可能会感到沮丧。


常用术语

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

  • Django – 提到框架时，大写 Django。 它仅在 Python 代码和 djangoproject.com 徽标中为小写。
  • email – 没有连字符。
  • MySQL、PostgreSQL、SQLite
  • SQL – 当提到 SQL 时，预期的发音应该是“Ess Queue Ell”而不是“sequel”。 因此，在像“返回 SQL 表达式”这样的短语中，“SQL”前面应该加“an”而不是“a”。
  • Python – 当提到语言时，大写 Python。
  • realize、customize、initialize等 – 使用美国的“ize”后缀，而不是“ise”。
  • subclass – 它是一个没有连字符的单词，既可以作为动词（“subclass that model”），也可以作为名词（“create a subclass”）。
  • Web、万维网、万维网——注意Web在提到万维网时总是大写。
  • website – 使用一个词，不用大写。


Django 特定的术语

  • model – 不大写。
  • template – 不大写。
  • URLconf – 使用三个大写字母，“conf”前没有空格。
  • view – 不大写。


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 将强制突出显示，尽管语法无效。

  • 为了提高可读性，请使用 .. admonition:: Descriptive title 而不是 .. note::。 谨慎使用这些盒子。

  • 使用这些标题样式：

    ===
One
===

Two
===

Three
-----

Four
~~~~

Five
^^^^

  • 使用 :rfc: 来引用 RFC 并尽可能尝试链接到相关部分。 例如，使用 :rfc:`2324#section-2.3.2` 或 :rfc:`Custom link text <2324#section-2.3.2>`。


特定于 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:`12345`

Django 的文档使用自定义 console 指令来记录涉及 django-admin.py、manage.py、python 等的命令行示例）。 在 HTML 文档中，它呈现了一个双选项卡 UI，一个选项卡显示 Unix 风格的命令提示符，第二个选项卡显示 Windows 提示符。

例如，您可以替换此片段： 

use this command:

.. code-block:: console

    $ python manage.py shell

有了这个： 

use this command:

.. console::

    $ python manage.py shell

注意两点：

  • 您通常会替换出现的 .. code-block:: console 指令。
  • 您不需要更改代码示例的实际内容。 您仍然在假设 Unix-y 环境下编写它（即 '$' 提示符号，'/' 作为文件系统路径组件分隔符等）

上面的示例将呈现一个带有两个选项卡的代码示例块。 第一个将显示： 

$ python manage.py shell

（与 .. code-block:: console 呈现的内容没有变化）。

第二个将显示： 

...\> py manage.py shell

记录新功能

我们对新功能的政策是：

所有新功能的文档都应该以明确指定功能仅在 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。 即使在块内，这样做通常也是多余的，因为这些注释分别呈现为“Django AB 中的新内容：”和“Django AB 中的更改”。

如果函数、属性等 添加了，也可以像这样使用 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` 来引用它。

这基本上就是所有东西组合在一起的方式。


拼写检查

在提交文档之前，最好运行拼写检查器。 您需要先安装 sphinxcontrib-spelling。 然后从 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 编写。



取自“https://cainiaojiaocheng.com/index.php?title=Django/docs/3.0.x/internals/contributing/writing-documentation&oldid=20673”
Powered by MediaWiki