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,
  93 you can use the `reStructuredText online renderer`__.  Thanks to Jiri
  94 Barton for `setting it up`__!
  95
  96 __ http://www.hosting4u.cz/jbar/rest/rest.html
  97 __ http://www.hosting4u.cz/jbar/rest/about.html
  98
  99
 100 Testimonials
 101 ============
 102
 103 The following testimonials are excerpts from unsolicited posts to
 104 mailing lists and the comp.lang.python newsgroup.  Being excerpts,
 105 there's often context missing, which sometimes tones down the message.
 106
 107 `Ueli Schlaepfer on Doc-SIG, 2002-03-28`__:
 108
 109 __ http://mail.python.org/pipermail/doc-sig/2002-March/002526.html
 110
 111     I have adopted reST as my tool of choice for producing notes while
 112     doing lab work (mostly in a matlab environment).  Since then, the
 113     quality of such documentation has increased noticeably, mostly for
 114     two reasons:
 115
 116     - I no longer need to switch to another tool, so the threshold has
 117       fallen to very low.  Note that "another tool" means Winword...
 118     - Still, I have a powerful set of markup constructs at my
 119       fingertips that let me create the kind of documents I need with
 120       more ease than any other tool I can think of.
 121
 122     Thanks to reST/DPS [now Docutils --ed], I'll soon be able to go
 123     ahead and apply the same tools for extracting documentation out of
 124     my Python code.  Hey, that's a printable and a browsable version
 125     *for free*!  Personally, I consider this a large benefit.
 126
 127     ... All essential constructs for everyday use are there, and much
 128     more if needed. ...
 129
 130 `Guido van Rossum, enthusiastic about PEP 287 but a bit hasty (see the
 131 follow-ups) on Python-Dev, 2002-04-02`__:
 132
 133 __ http://mail.python.org/pipermail/python-dev/2002-April/022131.html
 134
 135     Good PEP, David!  What's the next step?  Should the processing
 136     code be incorporated in the standard library?  Should we start
 137     converting the standard library docs to reStructuredText?
 138
 139 `Timothy Delaney on comp.lang.python, 2002-04-03`__:
 140
 141 __ http://mail.python.org/pipermail/python-list/2002-April/096013.html
 142
 143     I read through all the reStructuredText docs, comparing the text
 144     versions to the html versions.  I found the text versions to be
 145     *very* easy to read, whilst making it obvious in most cases when
 146     something was "special".
 147
 148     I particularly like the system of doing hyperlinks...
 149
 150     Definitely +1 from me ... I would really like a standard, clean
 151     docstring format.  Might make it easier to get my next project
 152     done in Python...
 153
 154 `Guido van Rossum on Python-Dev, 2002-04-03`__:
 155
 156 __ http://mail.python.org/pipermail/python-dev/2002-April/022212.html
 157
 158     I think that reStructuredText is a good format for marking up
 159     docstrings; it's probably as good as it gets given the
 160     requirements (a fairly elaborate feature set, yet more readable
 161     "in the raw" than HTML).
 162
 163 `Richard Jones on comp.lang.python, 2002-04-03`__:
 164
 165 __ http://mail.python.org/pipermail/python-list/2002-April/096117.html
 166
 167     How I see it is that ReST is a middle ground between markup and
 168     non-.  It has markup, and you can use it to the extreme.  Or you
 169     can follow some simple conventions (the most basic form of markup)
 170     and not worry about all the finer detail stuff. The difference
 171     between::
 172
 173         @section{The Section Title}
 174
 175     and::
 176
 177         The Section Title
 178         -----------------
 179
 180     Is pretty clearly to me that the second doesn't *look* like
 181     markup, even though it is.
 182
 183 `Guido van Rossum on Python-Dev, 2002-04-04`__:
 184
 185 __ http://mail.python.org/pipermail/python-dev/2002-April/022247.html
 186
 187     Structured text is really a great idea for certain situations;
 188     reST is a much better implementation of the idea than any versions
 189     I've seen before.
 190
 191 `Max M on comp.lang.python, 2002-04-05`__:
 192
 193 __ http://mail.python.org/pipermail/python-list/2002-April/096656.html
 194
 195     Any programmer can learn the basics in 15 minutes or less.
 196
 197     And it really is very very easy to write documents in it.  I do
 198     belive that if I were ever to write a book (again) I would write
 199     it in ReST.
 200
 201     And as far as I can tell from the specs, ReST solves most of the
 202     problems I have had with structured text.  A few things gets a
 203     little more complicated and some get simpler.  All in all a good
 204     bargain.
 205
 206     I would certainly use it.  I also hope that it gets integrated
 207     into Zope.
 208
 209 `David Abrahams on Python-Dev, 2002-04-06`__:
 210
 211 __ http://mail.python.org/pipermail/python-dev/2002-April/022443.html
 212
 213     Incidentally, I'm really excited about reST.  I've been looking
 214     for a tolerable markup for C++ comments, and reST looks like it
 215     might fit the bill.
 216
 217 `Eric Jones on Python-Dev, 2002-08-01`__:
 218
 219 __ http://mail.python.org/pipermail/python-dev/2002-August/027198.html
 220
 221     I would very much like to see reStructuredText, or some minor
 222     variation on it, move forward as a "standard" for doc-strings very
 223     soon.  I have long lamented not having a prescribed format *and*
 224     an associated processing tool suite included in the standard
 225     library.  Even if the format isn't perfect (I think it looks very
 226     good), it is time to pick a reasonable candidate and go.
 227
 228 This being the Internet, there were plenty of people opposed to the
 229 idea of reStructuredText, some vehemently.  Discovering *those* gems
 230 is left as an exercise for the reader.
 231
 232 .. _Docutils: index.html
 233 .. _StructuredText:
 234    http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/
 235 .. _Setext: mirror/setext.html
 236 .. _statemachine.py: docutils/statemachine.py
 237
 238 .. |reStructuredText| image:: rst.png
 239
 240 \f
 241 ..
 242    Local Variables:
 243    mode: indented-text
 244    indent-tabs-mode: nil
 245    sentence-end-double-space: t
 246    fill-column: 70
 247    End: