User Documentation

• A ReStructuredText Primer (HTML file, ortext source).

• Quick reStructuredText (user reference)

• reStructuredText Cheat Sheet (text only; 1 page for syntax, 1page directive & role reference)

Users who have questions or need assistance with Docutils orreStructuredText should post a message to theDocutils-users mailinglist.

Reference Documentation

• An Introduction to reStructuredText(includes theGoals of reStructuredText)

• History of reStructuredText

• reStructuredText Markup Specification

• reStructuredText Directives

• reStructuredText Interpreted Text Roles

Developer Documentation

• A Record of reStructuredText Syntax Alternatives

• Problems With StructuredText

Try it Online

If you want to try reStructuredText out without downloading Docutils, youcan play with the "simple online editor for reStructuredText" onhttp://rst.ninjs.org/

Testimonials

The following testimonials are excerpts from unsolicited posts tomailing 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 whiledoing lab work (mostly in a matlab environment). Since then, thequality of such documentation has increased noticeably, mostly fortwo reasons:

• I no longer need to switch to another tool, so the threshold hasfallen to very low. Note that "another tool" means Winword...

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

Thanks to reST/DPS [now Docutils --ed], I'll soon be able to goahead and apply the same tools for extracting documentation out ofmy Python code. Hey, that's a printable and a browsable versionfor free! Personally, I consider this a large benefit.

... All essential constructs for everyday use are there, and muchmore if needed. ...

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

Good PEP, David! What's the next step? Should the processingcode be incorporated in the standard library? Should we startconverting the standard library docs to reStructuredText?

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

I read through all the reStructuredText docs, comparing the textversions to the html versions. I found the text versions to bevery easy to read, whilst making it obvious in most cases whensomething was "special".

I particularly like the system of doing hyperlinks...

Definitely +1 from me ... I would really like a standard, cleandocstring format. Might make it easier to get my next projectdone in Python...

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

I think that reStructuredText is a good format for marking updocstrings; it's probably as good as it gets given therequirements (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 andnon-. It has markup, and you can use it to the extreme. Or youcan follow some simple conventions (the most basic form of markup)and not worry about all the finer detail stuff. The differencebetween:

@section{The Section Title}

and:

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

Is pretty clearly to me that the second doesn'tlook likemarkup, 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 versionsI'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 dobelieve that if I were ever to write a book (again) I would writeit in ReST.

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

I would certainly use it. I also hope that it gets integratedinto Zope.

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

Incidentally, I'm really excited about reST. I've been lookingfor a tolerable markup for C++ comments, and reST looks like itmight fit the bill.

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

I would very much like to see reStructuredText, or some minorvariation on it, move forward as a "standard" for doc-strings verysoon. I have long lamented not having a prescribed formatandan associated processing tool suite included in the standardlibrary. Even if the format isn't perfect (I think it looks verygood), it is time to pick a reasonable candidate and go.

This being the Internet, there were plenty of people opposed to theidea of reStructuredText, some vehemently. Discoveringthose gemsis left as an exercise for the reader.