Python 高手编程系列五百七十五：使用现实中的代码示例

Foo 和 bar 是坏成员。当读者试图通过一个使用示例来理解一段代码如何运行时，不
切实际的示例会让代码难以理解。
为什么不使用现实中的例子？通常的做法是确保每个代码示例都可以剪切并粘贴到一
个真正的程序中。
为了展示不良使用的例子，让我们假设我们想要展示如何使用 parse()函数：

from atomisator.parser import parse

让我们使用它:

stuff = parse(‘some-feed.xml’)
next(stuff)
{‘title’: ‘foo’, ‘content’: ‘blabla’}
一个更好的例子是解析器知道如何返回一个带有 parse 函数的 feed 内容，可用作顶层函数：
from atomisator.parser import parse

让我们使用它:

my_feed = parse(‘http://tarekziade.wordpress.com/feed’)
next(my_feed)
{‘title’: ‘eight tips to start with python’, ‘content’: ‘The first tip
is…, …’}
这种轻微的差别可能听起来有点过分，但实际上它使你的文档更有用。读者可以将
这些行复制到 shell 中，理解将一个 URL 解析为一个参数，并返回一个包含博客条目的迭
代器。
当然，给出一个现实的例子并不总是可能或可行的。这对于非常通用的代码尤其如此。
即使这本书也有很少出现的含糊不清的 foo 和 bar 字符串，在一些名称上下文不重要的地
方。总之，你应该总是努力把这种不切实际的例子的数量减少到最小。
使用轻量且充分的方法
在大多数敏捷方法中，文档不是首要的。相比细节文档，使软件正常工作是最重要的事
情。因此，Scott Ambler 在他的书 Agile Modeling:Effective Practices for eXtreme Programming
and the Unified Process 中解释了一个好的做法是定义真正的文档需求，而不是创建一个详
尽的文档集。
例如，让我们看一个简单项目 ianitor 的示例文档——它在 GitHub https://github.com/
ClearcodeHQ/ianitor 上。它是一个帮助在 Consul 服务发现集群中注册进程的工具，因此它
主要面向系统管理员。如果你看看它的文档，你会发现这只是一个单一的文档（README.md
文件）。它只解释了它是如何工作和如何使用它。从管理员的角度来看，这是足够的。他们
只需要知道如何配置和运行工具，没有其他人希望使用 ianitor。本文档通过回答这样一
个问题“我如何在我的服务器上使用 ianitor？”来限制其范围。
使用模板
维基百科上的每一页的布局都是相似的。一侧有用于总结日期或事实的文本框。在文
档的开头总是有一个目录，这个目录包含指向同一页面中的标题的链接。在结尾处总是有
一个参考部分。
用户习惯了它。例如，他们知道他们可以快速查看目录，如果他们没有找到他们正在
寻找的信息，他们将直接访问参考部分，以查看他们是否可以找到关于该主题的另一个网
站。这适用于维基百科上的任何页面。学习维基百科的方式可以让你更高效。
因此，使用模板强制文档的通用模式，可以使人们更有效地使用它们。他们习惯了结构，知道如何快速阅读它。
为每种文档提供模板还为作者提供了一个快速开始的脚手架。
reStructuredText 入门
reStructuredText 也被称为 reST（参考 http://docutils.sourceforge.net/rst.html）。它是一种
在 Python 社区中广泛用于文档化软件包的纯文本标记语言。reST 的优势在于，文本仍然可
读，因为标记语法不会像 LaTeX 那样混淆文本。
这里有一个文档示例，如下所示：
=====
Title
=====
Section 1
=========
This word has emphasis.
Section 2
=========
Subsection
::::::::::
Text.
reST 包含在 docutils 中，这个包提供了一套脚本来将 reST 文件转换为各种格式，
如 HTML，LaTeX，XML 或甚至 S5，Eric Meyer 的幻灯片对它进行了系统地显示（参考
http://meyerweb.com/eric/tools/s5）。
作者可以专注于内容，然后根据需要来决定如何渲染它。例如，Python 本身被记录在
reST 中，然后被渲染成 HTML 用来构建网站 http://docs.python.org，也可以渲染成很多其他
格式。
开始编写 reST 文档需要知道的最小元素集合如下。
● 章节结构（Section structure）。
● 列表（Lists）。
● 行内标记（Inline markup）。
● 文字块（Literal block）。
● 链接（Links）。
这一节是对语法的一个快速概述。包含更多信息的快速参考，这是开始使用 reST 的好
地方。
通过安装 docutils 来安装 reStructuredText：
$ pip install docutils
例如，docutils 包提供的 rst2html 脚本将给定的 reST 文件的输出为 HTML：
$ more text.txt
Title
=====
content.
$ rst2html.py text.txt

<?xml version="1.0" encoding="utf-8" ?>

…