Python 高手编程系列一千一百七十七：链接

只要在当前文档中提供了链接，就可以通过以两个点开头的特殊行将文本更改外部
链接，如下所示：
Try ‘Plone CMS’, it is great ! It is based on Zope.
… _‘Plone CMS’: http://plone.org
… _Zope: http://zope.org
通常的做法是将外部链接分组放到文档的末尾。当要链接的文本包含空格时，它必须
用`（反引号）字符包围。
也可以通过在文本中添加标记来使用内部链接，如下所示：
This is a code example
… _example:
::

1 + 1
2
Let’s continue our text, or maybe go back to
the example_.
章节也可以使用内部链接，如下所示：
==============
Document title
==============
Introduction to the document content.
Section 1
=========
First document section.
Section 2
=========
-> go back to ‘Section 1’_
构建文档
指导读者和作者的一个更简单的方法是向每个人提供帮助和指导，正如我们在本章前
面的章节中所学到的。
从作者的角度来看，这可以通过一组可重用的模板以及描述如何以及何时在项目中使
用它们的指南来完成。它被称为文档集（documentation portfolio）。
从读者的角度来看，重要的是能够无痛地浏览文档，并习惯于有效地查找信息。它是
通过构建文档格局（document landscape）来完成的。
构建文档集
软件项目可以有许多种类的文档，从直接引用代码的底层文档，到提供应用程序的高
层次视图的设计文档。
例如，Scott Ambler 在他的书 Agile Modeling: Effective Practices for eXtreme Programming
and the Unified Process 中定义了广泛的文档类型列表。他从早期规范到操作文档构建了一个
文档集。甚至包括项目管理文档，因此整个文档需求都是使用一组标准化的模板构建。
由于完整的文档集与用于构建软件的方法密切相关，本章将仅关注你可以根据特定需
求完成的公共子集。构建高效的文档集需要很长时间，因为它可以体现你的工作习惯。
软件项目中的一组常见文档可以分为 3 类。
● 设计：包括提供架构信息和底层设计信息的所有文档，例如类图或数据库图。
● 用法：包括有关如何使用软件的所有文档;可以是以一本手册和教程或模块级帮助
的形式。
● 操作：这提供了有关如何部署，升级或操作软件的指南。
设计
创建此类文档的重点是确保目标读者是完全知道的，内容范围有限的。因此，为作者
提供一点建议就是设计文档的通用模板尽量保持轻量级的结构。
这样的结构可能包括：
● 标题；
● 作者；
● 标签（关键字）；
● 说明（摘要）；
● 目标（谁应该读这篇文章？）；
● 内容（带图）；
● 参考的其他文件。
打印时，内容最多应为 3 页或 4 页，以确保限制范围。如果它变大，应该分成几个文
档或概述。
该模板还提供了作者的名字和一个标签列表来管理它的演变和简化分类。这将在本章
后面讨论。
reST 中的示例设计文档模板如下所示：
=========================================
Design document title
=========================================
:Author: Document Author
:Tags: document tags separated with spaces
:abstract:
Write here a small abstract about your design document.
… contents ::
Audience
========
Explain here who is the target readership.
Content
=======
Write your document here. Do not hesitate to split it in several
sections.
References
==========
Put here references, and links to other documents.
使用
使用文档描述软件的特定部分是如何使用的。本文档可以描述底层部分，如函数的工
作原理，也可以描述高层部分，如调用程序的命令行参数。这是框架应用程序中的文档的
最重要的部分，因为目标读者主要是将要重用代码的开发人员。
3 种主要的文件如下。
● 技巧：这是一个简短的文档，解释如何做某事。这种文件瞄准一个读者，并专注于
一个特定的主题。
● 教程：这是一个逐步的文档，说明如何使用软件的功能。本文档可以引用配方文档，
每个实例仅供一个读者使用。
● 模块助手：这是一个底层文档，用于说明模块包含的内容。当你通过模块调用内置
的帮助时，可以显示此文档。
技巧
一个技巧（recipe）文档解答一个非常具体的问题，并提供一个解决方案来解决问题。
例如，ActiveState 在线提供了一个庞大 Python 配方仓库，开发人员可以在其中描述如何使
用 Python 做事情（参考 http://code.activestate.com/recipes/langs/python/）。与单个区域/项目
相关的这样一组配方通常被称为攻略（cookbook）。
这些技巧必须简短，并且结构如下。
● 标题。
● 提交者。
● 最近更新时间。
● 版本。
● 类别。
● 说明。
● 源（源代码）。
● 讨论（解释代码的文字）。
● 评论（来自网络）。
通常，它们很长，超出一屏，但是却没有深入细节。这种结构完全符合软件的需要，
可以在通用结构中再进行调整，向其中添加目标读者，并且用标签替换类别：
● 标题（短句）。
● 作者。
● 标签（关键字）。
● 谁应该读这个？
● 先决条件（例如要读取的其他文档）。
● 问题（简短说明）。
● 解决方案（主文本，一个或两个屏幕）。
● 参考文献（指向其他文档的链接）。
上面没有日期和版本，因为像管理项目中的源代码一样管理项目文档。这意味着处理
文档的最好方法是通过版本控制系统进行管理。在大多数情况下，这与用于项目代码的代
码仓库完全相同。
一个简单的可重用的配方模板如下：
===========
Recipe name
===========
:Author: Recipe Author
:Tags: document tags separated with spaces
:abstract:
Write here a small abstract about your design document.
… contents ::
Audience
========
Explain here who is the target readership.
Prerequisites
=============
Write the list of prerequisites for implementing this recipe. This
can be additional documents, software, specific libraries, environment
settings or just anything that is required beyond the obvious language
interpreter.
Problem
=======
Explain the problem that this recipe is trying to solve.
Solution
========
Give solution to problem explained earlier. This is the core of a
recipe.
References
==========
Put here references, and links to other documents.
教程
教程和配方相比有着不同的目的。它不打算解决孤立的问题，而是描述如何逐步使
用应用程序的功能。这可能比配方更长，并且可能涉及应用程序的许多部分。例如，
Django 在其网站上提供了一个教程列表。Writing your first Django App, part1（参考 https://
docs.djangoproject.com/en/1.9/intro/tutorial01/）解释如何使用 Django 构建应用程序。
这种文件的结构如下所示。
● 标题（短句）。
● 作者。
● 标签（文字）。
● 说明（摘要）。
● 谁应该读这个？
● 先决条件（例如要读取的其他文档）。
● 教程（正文）。
● 参考文献（指向其他文档的链接）。
模块助手
模块助手模板是可以添加到我们的集合中的最后一个模板。模块助手指的是一个单独
的模块，它主要提供内容的描述以及使用示例。
一些工具可以通过使用 pydoc 提取 docstrings 和计算模块助手来自动构建这样的文档，
例如 Epydoc（参考 http://epydoc.sourceforge.net）。因此，可以基于内省 API 生成大量的文
档。通常在 Python 框架中会提供这种文档。例如，Plone 提供了一个 http://api.plone.org 服
务器，以保持模块助手的最新集合。
这种方法的主要问题如下。
● 无法智能的选择感兴趣的模块生成文档。
● 代码可能会被文档混淆。
此外，模块文档提供的例子有时可能涉及模块的多个部分，并且它们很难在函数和类
的 docstrings 之间进行拆分。模块的 docstring 的目的是可以在模块的顶部写入文本。但是
这最终得到一个由一个文本块组成的混合文件，而不是一个代码块。当代码小于总长度的 50%
时，这是相当模糊的。如果你是作者，这当然没问题。但是当人们尝试读取代码（而不是
文档）时，他们将不得不跳过 docstrings 部分。
另一种方法是将这些文本拆分到单独的文件中。然后通过手动的操作决定哪个 Python
模块具有模块助手文件。然后，文档可以从代码库中分离出来，并允许它们独立生存，我
们将在下一部分中看到。Python 的文档就是这样处理的。
事实上，许多开发人员不认同文档和代码分离比 docstrings 更好。这种方案法意味着文
档编写过程要完全纳入到开发周期中；否则文档就会很快过时。docstrings 方案通过让代码
及其用法示例之间的保持来解决这个问题，但是不能将其带到更高级别——一个可以用作
纯文本文件一部分的文档。
模块助手的模板非常简单，因为它在内容写入之前只包含一些元数据。目标读者没有
定义，直到有希望使用此模块的开发人员。
● 标题（模块名称）。
● 作者。
● 标签（文字）。
● 内容。
操作
操作文档用于描述如何操作软件，需要考虑以下几点。
● 安装和部署文档。
● 管理文件。
● 常见问题（FAQ）文档。
● 解释人们如何贡献，请求帮助或提供反馈的文档。
这些文档非常具体，但他们可以使用前面部分中定义的教程模板。