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 tipis…, …’}这种轻微的差别可能听起来有点过分但实际上它使你的文档更有用。读者可以将这些行复制到 shell 中理解将一个 URL 解析为一个参数并返回一个包含博客条目的迭代器。当然给出一个现实的例子并不总是可能或可行的。这对于非常通用的代码尤其如此。即使这本书也有很少出现的含糊不清的 foo 和 bar 字符串在一些名称上下文不重要的地方。总之你应该总是努力把这种不切实际的例子的数量减少到最小。使用轻量且充分的方法在大多数敏捷方法中文档不是首要的。相比细节文档使软件正常工作是最重要的事情。因此Scott Ambler 在他的书 Agile Modeling:Effective Practices for eXtreme Programmingand 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 那样混淆文本。这里有一个文档示例如下所示TitleSection 1Thiswordhas emphasis.Section 2Subsection::::::::::Text.reST 包含在 docutils 中这个包提供了一套脚本来将 reST 文件转换为各种格式如 HTMLLaTeXXML 或甚至 S5Eric 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.txtTitlecontent.$ rst2html.py text.txt?xml version1.0 encodingutf-8 ?…