reStructuredText

Docutils 的标记语法和解析器组件

Date

$Date$

注解

“reStructuredText” 是一个单词，不是两个！

reStructuredText 是一个易于阅读的、所见即所得的纯文本标记语法和解析器系统。它对于内联程序文档（如 Python 文档字符串）、快速创建简单网页和独立文档都很有用。reStructuredText 是为特定应用领域的可扩展性而设计的。reStructuredText 解析器是 Docutils 的一个组件。reStructuredText 是对 StructuredText 和 Setext 轻量级标记系统的修订和重新解释。

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

请参阅 statemachine.py 以获得使用 reStructuredText 完整文档的 Python 模块示例。

用户文档

Users who have questions or need assistance with Docutils or reStructuredText should post a message to the Docutils-users mailing list.

Reference Documentation

Developer Documentation

How-To’s

Try it Online

If you want to try reStructuredText out without downloading Docutils, you can play with the “simple online editor for reStructuredText” on http://rst.ninjs.org/

Testimonials

The following testimonials are excerpts from unsolicited posts to mailing lists and the comp.lang.python newsgroup. Being excerpts, there’s often context missing, which sometimes tones down the message.

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

I have adopted reST as my tool of choice for producing notes while doing lab work (mostly in a matlab environment). Since then, the quality of such documentation has increased noticeably, mostly for two reasons:

  • I no longer need to switch to another tool, so the threshold has fallen to very low. Note that “another tool” means Winword…

  • Still, I have a powerful set of markup constructs at my fingertips that let me create the kind of documents I need with more ease than any other tool I can think of.

Thanks to reST/DPS [now Docutils –ed], I’ll soon be able to go ahead and apply the same tools for extracting documentation out of my Python code. Hey, that’s a printable and a browsable version for free! Personally, I consider this a large benefit.

… All essential constructs for everyday use are there, and much more if needed. …

Guido van Rossum, enthusiastic about PEP 287 but a bit hasty (see the follow-ups) on Python-Dev, 2002-04-02:

Good PEP, David! What’s the next step? Should the processing code be incorporated in the standard library? Should we start converting the standard library docs to reStructuredText?

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

I read through all the reStructuredText docs, comparing the text versions to the html versions. I found the text versions to be very easy to read, whilst making it obvious in most cases when something was “special”.

I particularly like the system of doing hyperlinks…

Definitely +1 from me … I would really like a standard, clean docstring format. Might make it easier to get my next project done in Python…

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

I think that reStructuredText is a good format for marking up docstrings; it’s probably as good as it gets given the requirements (a fairly elaborate feature set, yet more readable “in the raw” than HTML).

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

How I see it is that ReST is a middle ground between markup and non-. It has markup, and you can use it to the extreme. Or you can follow some simple conventions (the most basic form of markup) and not worry about all the finer detail stuff. The difference between:

@section{The Section Title}

and:

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

Is pretty clearly to me that the second doesn’t look like markup, even though it is.

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

Structured text is really a great idea for certain situations; reST is a much better implementation of the idea than any versions I’ve seen before.

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

Any programmer can learn the basics in 15 minutes or less.

And it really is very very easy to write documents in it. I do believe that if I were ever to write a book (again) I would write it in ReST.

And as far as I can tell from the specs, ReST solves most of the problems I have had with structured text. A few things gets a little more complicated and some get simpler. All in all a good bargain.

I would certainly use it. I also hope that it gets integrated into Zope.

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

Incidentally, I’m really excited about reST. I’ve been looking for a tolerable markup for C++ comments, and reST looks like it might fit the bill.

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

I would very much like to see reStructuredText, or some minor variation on it, move forward as a “standard” for doc-strings very soon. I have long lamented not having a prescribed format and an associated processing tool suite included in the standard library. Even if the format isn’t perfect (I think it looks very good), it is time to pick a reasonable candidate and go.

This being the Internet, there were plenty of people opposed to the idea of reStructuredText, some vehemently. Discovering those gems is left as an exercise for the reader.