web/rst.txt

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