标记语法和解析器组件

注解

“reStructuredText” 是 一个 字，不 是两个！

目录

• 标记语法和解析器组件

  • 用户文档

  • 参考文档

  • 开发者文档

    • 基本知识

  • 在线尝试

  • 褒奖

reStructuredText是一个易于阅读，你所看到的纯文本标记语法和解析器系统。它对于内联程序文档(例如Python文档字符串)，快速创建简单的Web页面以及独立文档非常有用。 reStructuredText旨在用于特定应用程序域的可扩展性。 reStructuredText解析器是 Docutils 的一个组件。 reStructuredText是对 StructuredText 和 Setext 轻量级标记系统的修订和重新解释。

reStructuredText的主要目标是定义和实现在Python文档字符串和其他文档域中使用的标记语法，该语法可读且简单，但功能强大，非常重要。标记的预期目的是将reStructuredText文档转换为有用的结构化数据格式。

有关使用reStructuredText完整记录的Python模块的示例，请参阅statemachine.py。

用户文档

• A ReStructuredText Primer (HTML文件，或 text source)。

• Quick reStructuredText (用户参考)

• reStructuredText Cheat Sheet (仅限文本; 1页用于语法，1页指令和角色参考)

对Docutils或reStructuredText有疑问或需要帮助的用户应向 Docutils-users 邮件列表发送消息。

参考文档

• An Introduction to reStructuredText (包括reStructuredText的 Goals 和 History)

• reStructuredText Markup Specification

• reStructuredText Directives

• reStructuredText Interpreted Text Roles

开发者文档

• A Record of reStructuredText Syntax Alternatives

• Problems With StructuredText

基本知识

• Creating reStructuredText Directives

• Creating reStructuredText Interpreted Text Roles

在线尝试

如果你想在不下载Docutils的情况下尝试使用reStructuredText，你可以在http://rst.ninjs.org/上玩“reStructuredText”的“简单在线编辑器”。

褒奖

以下推荐书摘录自未经请求的帖子到邮件列表和comp.lang.python新闻组。作为摘录，经常缺少上下文，这有时会消除信息。

Ueli Schlaepfer on Doc-SIG, 2002-03-28:

我已经采用reST作为我在做实验室工作时制作笔记的首选工具(主要是在matlab环境中)。从那以后，这些文件的质量明显增加，主要有两个原因:

• 我不再需要切换到另一个工具，因此阈值已降至非常低。请注意 “另一个工具” 表示Winword …

• 尽管如此，我还是拥有一套功能强大的标记结构，让我能够比我能想到的任何其他工具更轻松地创建所需的文档。

感谢 reST/DPS [现在的 Docutils –ed]，我很快就可以继续使用相同的工具从我的Python代码中提取文档。嘿，这是一个可打印和可浏览的版本 免费 ！就个人而言，我认为这是一个很大的好处。

… 日常使用的所有基本构造都在那​​里，如果需要还有更多。 …

Guido van Rossum，热衷于PEP 287，但有点仓促(参见后续内容)关于Python-Dev， 2002-04-02:

好的PEP，大卫！下一步是什么？处理代码应该包含在标准库中吗？我们应该开始将标准库文档转换为reStructuredText吗？

Timothy Delaney on comp.lang.python, 2002-04-03:

我阅读了所有reStructuredText文档，将文本版本与html版本进行了比较。我发现文本版本*非常容易阅读，而在大多数情况下，当某些内容是“特殊”时，它显而易见。

我特别喜欢做超链接的系统……

绝对+1我…我真的很喜欢标准，干净的文档字符串格式。可能会让我更容易在Python中完成我的下一个项目…

Guido van Rossum on Python-Dev, 2002-04-03:

我认为reStructuredText是一种用于标记文档字符串的良好格式;它可能与给定的要求一样好(一个相当复杂的功能集，但在原始中比HTML更可读)。

Richard Jones on comp.lang.python, 2002-04-03:

我如何看待ReST是标记和非标记之间的中间立场。它有标记，你可以使用它到极致。或者你可以遵循一些简单的约定(最基本的标记形式)，而不用担心所有更精细的细节。和…之间的不同:

@section{The Section Title}

and:

The Section Title
-----------------

对我来说很清楚的是，第二个看起来不像标记，即使它是。

Guido van Rossum on Python-Dev, 2002-04-04:

对于某些情况，结构化文本确实是个好主意;与以前见过的任何版本相比，reST是一个更好的实现。

Max M on comp.lang.python, 2002-04-05:

任何程序员都可以在15分钟或更短的时间内学习基础知识。

在其中编写文档真的非常容易。我确实相信，如果我曾经写过一本书(再次)，我会用ReST写的。

据我所知，ReST解决了我在结构化文本中遇到的大部分问题。有些事情变得复杂一些，有些变得更简单。总而言之，讨价还价。

我当然会用它。我也希望它融入Zope。

David Abrahams on Python-Dev, 2002-04-06:

顺便说一句，我对reST感到非常兴奋。我一直在寻找一个可容忍的C ++注释标记，而reST看起来可能符合要求。

Eric Jones on Python-Dev, 2002-08-01:

我非常希望看到reStructuredText或其中的一些小变化，很快就会成为doc-strings的“标准”。我一直感叹没有规定的格式*和标准库中包含的相关处理工具套件。即使格式不完美(我觉得它看起来非常好)，现在是时候挑选一个合理的候选人了。

这是互联网，有很多人反对reStructuredText的想法，有些人强烈反对。发现*那些*宝石留给读者练习。