web/rst.txt

   1 ====================
   2  |reStructuredText|
   3 ====================
   4 -------------------------------------------------
   5  Markup Syntax and Parser Component of Docutils_
   6 -------------------------------------------------
   7
   8 :Date: $Date$
   9
  10 .. Note:: "reStructuredText" is **ONE** word, *not two!*
  11
  12 .. contents::
  13
  14 reStructuredText is an easy-to-read, what-you-see-is-what-you-get
  15 plaintext markup syntax and parser system.  It is useful for in-line
  16 program documentation (such as Python docstrings), for quickly
  17 creating simple web pages, and for standalone documents.
  18 reStructuredText is designed for extensibility for specific
  19 application domains.  The reStructuredText parser is a component of
  20 Docutils_.  reStructuredText is a revision and reinterpretation of the
  21 StructuredText_ and Setext_ lightweight markup systems.
  22
  23 The primary goal of reStructuredText is to define and implement a
  24 markup syntax for use in Python docstrings and other documentation
  25 domains, that is readable and simple, yet powerful enough for
  26 non-trivial use.  The intended purpose of the markup is the conversion
  27 of reStructuredText documents into useful structured data formats.
  28
  29 See statemachine.py_ for an example of a Python module fully
  30 documented using reStructuredText.
  31
  32
  33 User Documentation
  34 ==================
  35
  36 - `A ReStructuredText Primer`__ (HTML file, or `text source`__).
  37 - `Quick reStructuredText`__ (user reference)
  38 - `reStructuredText Cheat Sheet`__ (text only; 1 page for syntax, 1
  39   page directive & role reference)
  40
  41 Users who have questions or need assistance with Docutils or
  42 reStructuredText should post a message to the Docutils-users_ mailing
  43 list.
  44
  45 __ docs/user/rst/quickstart.html
  46 __ docs/user/rst/quickstart.txt
  47 __ docs/user/rst/quickref.html
  48 __ docs/user/rst/cheatsheet.txt
  49 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
  50
  51
  52 Reference Documentation
  53 =======================
  54
  55 - `An Introduction to reStructuredText`__ (includes the Goals__ and
  56   History__ of reStructuredText)
  57 - `reStructuredText Markup Specification`__
  58 - `reStructuredText Directives`__
  59 - `reStructuredText Interpreted Text Roles`__
  60
  61 __ docs/ref/rst/introduction.html
  62 __ docs/ref/rst/introduction.html#goals
  63 __ docs/ref/rst/introduction.html#history
  64 __ docs/ref/rst/restructuredtext.html
  65 __ docs/ref/rst/directives.html
  66 __ docs/ref/rst/roles.html
  67
  68
  69 Developer Documentation
  70 =======================
  71
  72 - `A Record of reStructuredText Syntax Alternatives`__
  73 - `Problems With StructuredText`__
  74
  75 __ docs/dev/rst/alternatives.html
  76 __ docs/dev/rst/problems.html
  77
  78
  79 How-To's
  80 --------
  81
  82 - `Creating reStructuredText Directives`__
  83 - `Creating reStructuredText Interpreted Text Roles`__
  84
  85 __ docs/howto/rst-directives.html
  86 __ docs/howto/rst-roles.html
  87
  88
  89 Try it Online
  90 =============
  91
  92 If you want to try reStructuredText out without downloading Docutils, you
  93 can play with the "simple online editor for reStructuredText" on
  94 http://rst.ninjs.org/
  95
  96
  97 Testimonials
  98 ============
  99
 100 The following testimonials are excerpts from unsolicited posts to
 101 mailing lists and the comp.lang.python newsgroup.  Being excerpts,
 102 there's often context missing, which sometimes tones down the message.
 103
 104 `Ueli Schlaepfer on Doc-SIG, 2002-03-28`__:
 105
 106 __ http://mail.python.org/pipermail/doc-sig/2002-March/002526.html
 107
 108     I have adopted reST as my tool of choice for producing notes while
 109     doing lab work (mostly in a matlab environment).  Since then, the
 110     quality of such documentation has increased noticeably, mostly for
 111     two reasons:
 112
 113     - I no longer need to switch to another tool, so the threshold has
 114       fallen to very low.  Note that "another tool" means Winword...
 115     - Still, I have a powerful set of markup constructs at my
 116       fingertips that let me create the kind of documents I need with
 117       more ease than any other tool I can think of.
 118
 119     Thanks to reST/DPS [now Docutils --ed], I'll soon be able to go
 120     ahead and apply the same tools for extracting documentation out of
 121     my Python code.  Hey, that's a printable and a browsable version
 122     *for free*!  Personally, I consider this a large benefit.
 123
 124     ... All essential constructs for everyday use are there, and much
 125     more if needed. ...
 126
 127 `Guido van Rossum, enthusiastic about PEP 287 but a bit hasty (see the
 128 follow-ups) on Python-Dev, 2002-04-02`__:
 129
 130 __ http://mail.python.org/pipermail/python-dev/2002-April/022131.html
 131
 132     Good PEP, David!  What's the next step?  Should the processing
 133     code be incorporated in the standard library?  Should we start
 134     converting the standard library docs to reStructuredText?
 135
 136 `Timothy Delaney on comp.lang.python, 2002-04-03`__:
 137
 138 __ http://mail.python.org/pipermail/python-list/2002-April/096013.html
 139
 140     I read through all the reStructuredText docs, comparing the text
 141     versions to the html versions.  I found the text versions to be
 142     *very* easy to read, whilst making it obvious in most cases when
 143     something was "special".
 144
 145     I particularly like the system of doing hyperlinks...
 146
 147     Definitely +1 from me ... I would really like a standard, clean
 148     docstring format.  Might make it easier to get my next project
 149     done in Python...
 150
 151 `Guido van Rossum on Python-Dev, 2002-04-03`__:
 152
 153 __ http://mail.python.org/pipermail/python-dev/2002-April/022212.html
 154
 155     I think that reStructuredText is a good format for marking up
 156     docstrings; it's probably as good as it gets given the
 157     requirements (a fairly elaborate feature set, yet more readable
 158     "in the raw" than HTML).
 159
 160 `Richard Jones on comp.lang.python, 2002-04-03`__:
 161
 162 __ http://mail.python.org/pipermail/python-list/2002-April/096117.html
 163
 164     How I see it is that ReST is a middle ground between markup and
 165     non-.  It has markup, and you can use it to the extreme.  Or you
 166     can follow some simple conventions (the most basic form of markup)
 167     and not worry about all the finer detail stuff. The difference
 168     between::
 169
 170         @section{The Section Title}
 171
 172     and::
 173
 174         The Section Title
 175         -----------------
 176
 177     Is pretty clearly to me that the second doesn't *look* like
 178     markup, even though it is.
 179
 180 `Guido van Rossum on Python-Dev, 2002-04-04`__:
 181
 182 __ http://mail.python.org/pipermail/python-dev/2002-April/022247.html
 183
 184     Structured text is really a great idea for certain situations;
 185     reST is a much better implementation of the idea than any versions
 186     I've seen before.
 187
 188 `Max M on comp.lang.python, 2002-04-05`__:
 189
 190 __ http://mail.python.org/pipermail/python-list/2002-April/096656.html
 191
 192     Any programmer can learn the basics in 15 minutes or less.
 193
 194     And it really is very very easy to write documents in it.  I do
 195     belive that if I were ever to write a book (again) I would write
 196     it in ReST.
 197
 198     And as far as I can tell from the specs, ReST solves most of the
 199     problems I have had with structured text.  A few things gets a
 200     little more complicated and some get simpler.  All in all a good
 201     bargain.
 202
 203     I would certainly use it.  I also hope that it gets integrated
 204     into Zope.
 205
 206 `David Abrahams on Python-Dev, 2002-04-06`__:
 207
 208 __ http://mail.python.org/pipermail/python-dev/2002-April/022443.html
 209
 210     Incidentally, I'm really excited about reST.  I've been looking
 211     for a tolerable markup for C++ comments, and reST looks like it
 212     might fit the bill.
 213
 214 `Eric Jones on Python-Dev, 2002-08-01`__:
 215
 216 __ http://mail.python.org/pipermail/python-dev/2002-August/027198.html
 217
 218     I would very much like to see reStructuredText, or some minor
 219     variation on it, move forward as a "standard" for doc-strings very
 220     soon.  I have long lamented not having a prescribed format *and*
 221     an associated processing tool suite included in the standard
 222     library.  Even if the format isn't perfect (I think it looks very
 223     good), it is time to pick a reasonable candidate and go.
 224
 225 This being the Internet, there were plenty of people opposed to the
 226 idea of reStructuredText, some vehemently.  Discovering *those* gems
 227 is left as an exercise for the reader.
 228
 229 .. _Docutils: index.html
 230 .. _StructuredText:
 231    http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/
 232 .. _Setext: mirror/setext.html
 233 .. _statemachine.py: docutils/statemachine.py
 234
 235 .. |reStructuredText| image:: rst.png
 236
 237 \f
 238 ..
 239    Local Variables:
 240    mode: indented-text
 241    indent-tabs-mode: nil
 242    sentence-end-double-space: t
 243    fill-column: 70
 244    End: