我的书签
添加书签
移除书签18.3 通过RST标记提供更好的输出
我们可以使用一个更完善的工具集使文档变得更好。有几件事情我们希望能做，如下所示。
- 调整演示文档，包含一些重点标记，例如粗体、斜体和颜色。
- 为参数、返回值、异常和Python对象间的交叉引用提供语义标记。
- 提供查看代码的链接。
- 过滤包含的或者被拒绝的代码。我们可以调整这个筛选机制来包含或者去除一些组件和成员：标准库模块、以开头的私有成员、以开头的系统成员或者基类成员。
- 修改CSS为生成的HTML页面提供不同的样式。
我们可以通过在文档注释中使用更完整的标记满足前两个要求，我们需要用到RST标记语言。为了满足后3个要求，我们需要一个额外的工具。
一旦我们开始使用更完整的标记，就可以拓展HTML，让它包含可以生成格式更好的文档的LaTex。这使得我们可以从一个单独的输入源生成除HTML外的PostScript或者PDF输出。
RST是简单的轻量级标记。Python的docutils项目有许多很好的教程和总结，更多的细节可以参见http://docutils.sourceforge.net 。
下面的页面有一个快速概览：http://docutils.sourceforge.net/docs/user/rst/quickstart.html 。
docutils工具集的目的是为我们提供一个非常聪明的解析器，这样我们就可以使用非常简单的标记。HTML和XML依赖于相对简单的解析器，把创建复杂标记的职责留给用户（或者编辑工具）。XML和HTML可以在各种不同的情景中使用，但是docutils解析器主要针对自然语言文本。正是因为这种相对狭窄的针对面，docutils能够基于空白行和一些ASCII的标点推断我们的目的。
对我们来说，docutils解析器可以解析下面3种基本的文本。
- 文本块：段落、头、列表、引用、代码示例和doctest块。这些文本通过空行分隔。
- 内联标记可以出现在文本块中。这包括用简单的标点在文本块中标记字符。有两种内联标记，我们会在后面的部分介绍一些关于这两种标记的细节。
- 指令也是文本块，但是指令以..作为每行开头的前两个字符。指令是开放式的并且可以被扩展为向docutils中添加功能的工具。
18.3.1 文本块
文本块就是一个简单的段落，通过空行与其他段落分隔。这是RST标记的基本单元。RST基于使用的模式可以识别许多不同种类的段落，下面是一个标题的例子。
This Is A Heading
=================
这行文字会被解析为标题，因为它以一连串的特殊字符作为下划线。
docutils解析器完全根据标题的使用方式推断出标题的层次。我们必须与标题和它们的嵌套方式保持一致。这样的做法有助于选择和保持一个标准。这样的做法还有助于保持文档的平坦，避免引入复杂的嵌套标题。通常只需要3个层次，这意味着我们可以使用====、——和~~~~作为这3个层次。
列表项目以特殊字符开头，内容必须缩进。Python和RST都使用4个空格的缩进。但是，几乎可以使用任何一致的缩进都可以。
Bullet Lists
- Leading Special Character.
- Consistent Indent.
注意段落间的空行。对于某些类型的简单项目列表，空行不是必需的。通常，使用空行会是一个好主意。
数字列表以数字或者字符和罗马数字开头。如果需要自动生成数字，可以用#作为列表项目的开头。
Number Lists
1. Leading digit or letter.
2. Auto-numbering with #.
#. Looks like this.
我们可以利用这种缩进规则在列表中创建列表。它可能很复杂，但是docutils的RST解析器通常都能够理解你的意图。
引用文字块就是简单的缩进文本。
Here's a paragraph with a cool quote.
Cool quotes might include a tip.
Here's another paragraph.
通过::双冒号表示代码示例，代码块会缩进并且以空行结束。尽管::可以放在行末或者自身作为独立的行，将::作为独立的行让我们可以更容易找到代码示例。
下面是代码示例。
::
x = Deck()
first_card= x.pop()
This shows two lines of code. It will be distinguished from surrounding text.
docutils解析器也会定位doctest的素材并将它设定为特殊格式，与处理代码块的方法类似。它们以>>>开头，以空行结束。
下面是doctest生成的一些示例输出。
>>> x= Unsorted_Deck()
>>> x.pop()
'A♣'
测试的输入结果中最后的空行是必需的，但是这个空行也很容易被忽略。
18.3.2 RST内联标记
在大多数文本块中，我们可以包含内联标记。但不能在代码示例或doctest块中包含内联标记。请注意，也不能内嵌内联标记。
RST内联标记包含许多常见的ASCII文本处理。例如，我们通常用emphasis和strong emphasis分别生成斜体和粗体。我们可能想强调文本块中的代码段，用"literal"强制使用等宽字体。
我们也可以在内联标记中包含交叉引用。尾随的意味着指向引用，前置的意味着指向目标。例如，我们可能以'some phrase'作为引用。然后，可以使用'some phrase'作为这个引用的目标。我们不需要为节标题提供显式的目标：我们可以引用'This Is A Heading'_，因为所有的节标题都已经定义为目标。对于HTML输出，这会生成我们所预期的<a>标记。对于PDF输出，这会生成文本链接。
我们不能内嵌内联标记。很少有情况会需要使用内联标记，使用太多的排版技巧反而会带来视觉上的混乱。如果我们需要使用很多排版技巧，那么我们可能应该直接用LaTex。
内联标记也可以包含显式的角色指示器。写法是:role:跟着'text'。简单的RST角色相对比较少。我们可以考虑用:code:'some code'明确表示文本中有代码存在。当我们介绍Sphinx时，有许多角色指示器。使用显式的角色可以提供大量的语义信息。
当所做的事情包含了复杂的数学概念时，我们可以考虑用LaTex的数学排版功能。这种功能使用:math:角色，它看起来类似后面这样：:math:'a=\pi r^2'。
角色是开放式的。我们可以为docutils提供一个配置来添加新的角色。
18.3.3 RST指令
RST也包含指令。指令写在以..开头的块中，可能会包含一些缩进的内容，也可能包含一些参数。RST包含了大量的可以用来创建更完善文档的指令。对于准备文档字符串，我们很少会使用过多的指令。指令是开放式的，例如Sphinx这样的工具会通过添加指令生成更完善的文档。
3个常用的指令是image、csv-table和math。如果我们的文档中包含一张图片，我们可以用下面的方式包含它。
.. image:: media/some_file.png
:width: 6in
我们将文件命名为media/some _ file.png。我们也为它提供了width参数来确保我们的图片与文档页的布局吻合。还有其他的一些参数可以用来调整图片的显示。
- :align：我们可以提供关键字，例如top、middle、bottom、left、center或者right。这个值作为HTML的<img>标记的align属性的值。
- :alt：这是另外一种图片的表示方法，这个值被作为HTML的<img>标记的alt属性的值。
- :height：这个参数代表图片的高度。
- :scale：这个参数代表比例因子，可以用这个因子代替高度和宽度。
- :width：这个参数代表图片的宽度。
- :target：这是图片的目标超链接。这可以是一个完整的URI或者一个'name'_表单的RST引用。
对于高度和宽度，CSS中任何长度的单元都可以使用。这包括em（元素字体的高度）、ex（字符“x”的高度）、px（像素）和绝对尺寸：in、cm、mm、pt（point）和pc（pica）。
我们可以用以下面的方式在文档中包含一个表。
.. csv-table:: Suits
:header: symbol, name
"'♣'", Clubs
"'♦'", Diamonds
"'♥'", Hearts
"'♠'", Spades
这允许我们用简单的CSV标记表示一个复杂的HTML表格的数据。我们可以用math指令表示一个更复杂的公式。
.. math::
c = 2 \pi r
这允许我们编写作为独立方程式的更复杂的LaTex数学表达式。这些表达式也可以进行编号和交叉引用。
18.3.4 学习RST
学习使用RST的一种方法是安装docutils并且用rst2html.py脚本来解析RST文档，然后将它转换为HTML页面。通过一个简单的测试文档就可以轻松地向我们展示RST的不同特性。
所有项目的需求、架构和文档都可以用RST编写，然后转换为HTML或者LaTex。用RST编写用户故事，然后将这些文件放入一个可以随着这些故事被讨论、投入开发和实现而重新组织的目录中，这样的做法是相对快速的。一些更复杂的工具可能并不会比docutils更具有价值。
使用纯文本文件和RST标记的优势是我们可以同时轻松地管理文档和代码。我们没有使用专用的文字处理文件格式。我们没有使用冗长的HTML或者XML标记，这些标记语法在真实项目中必须压缩。我们只是存储更多的文本和源代码。
如果我们使用RST创建文档，也可以使用rst2latex.py脚本创建.tex文件，通过运行LaTex工具集可以基于这个文件创建postscript或者PDF文档。这需要用到LaTex工具集，通常，我们会使用 TexLive。参见http://www.tug.org/texlive/，这个页面介绍了一组更完善的工具，可以将Tex转换为优雅的最终文件。TexLive包含了可以用来将LaTex的输入转换为PDF文件的pdfTex工具。
