1
=====================================
2
An Introduction to reStructuredText
3
=====================================
5
:Contact: goodger@users.sourceforge.net
6
:Revision: $Revision: 3974 $
7
:Date: $Date: 2005-10-29 16:39:45 +0200 (Sat, 29 Oct 2005) $
8
:Copyright: This document has been placed in the public domain.
10
reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get
11
plaintext markup syntax and parser system. It is useful for inline
12
program documentation (such as Python docstrings), for quickly
13
creating simple web pages, and for standalone documents.
14
reStructuredText_ is a proposed revision and reinterpretation of the
15
StructuredText_ and Setext_ lightweight markup systems.
17
reStructuredText is designed for extensibility for specific
18
application domains. Its parser is a component of Docutils_.
20
This document defines the goals_ of reStructuredText and provides a
21
history_ of the project. It is written using the reStructuredText
22
markup, and therefore serves as an example of its use. For a gentle
23
introduction to using reStructuredText, please read `A
24
ReStructuredText Primer`_. The `Quick reStructuredText`_ user
25
reference is also useful. The `reStructuredText Markup
26
Specification`_ is the definitive reference. There is also an
27
analysis of the `Problems With StructuredText`_.
29
ReStructuredText's web page is
30
http://docutils.sourceforge.net/rst.html.
32
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
34
http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage
35
.. _Setext: http://docutils.sourceforge.net/mirror/setext.html
36
.. _Docutils: http://docutils.sourceforge.net/
37
.. _A ReStructuredText Primer: ../../user/rst/quickstart.html
38
.. _Quick reStructuredText: ../../user/rst/quickref.html
39
.. _reStructuredText Markup Specification: restructuredtext.html
40
.. _Problems with StructuredText: ../../dev/rst/problems.html
46
The primary goal of reStructuredText_ is to define a markup syntax for
47
use in Python docstrings and other documentation domains, that is
48
readable and simple, yet powerful enough for non-trivial use. The
49
intended purpose of the reStructuredText markup is twofold:
51
- the establishment of a set of standard conventions allowing the
52
expression of structure within plaintext, and
54
- the conversion of such documents into useful structured data
57
The secondary goal of reStructuredText is to be accepted by the Python
58
community (by way of being blessed by PythonLabs and the BDFL [#]_) as
59
a standard for Python inline documentation (possibly one of several
60
standards, to account for taste).
62
.. [#] Python's creator and "Benevolent Dictator For Life",
65
To clarify the primary goal, here are specific design goals, in order,
66
beginning with the most important:
68
1. Readable. The marked-up text must be easy to read without any
69
prior knowledge of the markup language. It should be as easily
70
read in raw form as in processed form.
72
2. Unobtrusive. The markup that is used should be as simple and
73
unobtrusive as possible. The simplicity of markup constructs
74
should be roughly proportional to their frequency of use. The most
75
common constructs, with natural and obvious markup, should be the
76
simplest and most unobtrusive. Less common constructs, for which
77
there is no natural or obvious markup, should be distinctive.
79
3. Unambiguous. The rules for markup must not be open for
80
interpretation. For any given input, there should be one and only
81
one possible output (including error output).
83
4. Unsurprising. Markup constructs should not cause unexpected output
84
upon processing. As a fallback, there must be a way to prevent
85
unwanted markup processing when a markup construct is used in a
86
non-markup context (for example, when documenting the markup syntax
89
5. Intuitive. Markup should be as obvious and easily remembered as
90
possible, for the author as well as for the reader. Constructs
91
should take their cues from such naturally occurring sources as
92
plaintext email messages, newsgroup postings, and text
93
documentation such as README.txt files.
95
6. Easy. It should be easy to mark up text using any ordinary text
98
7. Scalable. The markup should be applicable regardless of the length
101
8. Powerful. The markup should provide enough constructs to produce a
102
reasonably rich structured document.
104
9. Language-neutral. The markup should apply to multiple natural (as
105
well as artificial) languages, not only English.
107
10. Extensible. The markup should provide a simple syntax and
108
interface for adding more complex general markup, and custom
111
11. Output-format-neutral. The markup will be appropriate for
112
processing to multiple output formats, and will not be biased
113
toward any particular format.
115
The design goals above were used as criteria for accepting or
116
rejecting syntax, or selecting between alternatives.
118
It is emphatically *not* the goal of reStructuredText to define
119
docstring semantics, such as docstring contents or docstring length.
120
These issues are orthogonal to the markup syntax and beyond the scope
121
of this specification.
123
Also, it is not the goal of reStructuredText to maintain compatibility
124
with StructuredText_ or Setext_. reStructuredText shamelessly steals
125
their great ideas and ignores the not-so-great.
129
Due to the nature of the problem we're trying to solve (or,
130
perhaps, due to the nature of the proposed solution), the above
131
goals unavoidably conflict. I have tried to extract and distill
132
the wisdom accumulated over the years in the Python Doc-SIG_
133
mailing list and elsewhere, to come up with a coherent and
134
consistent set of syntax rules, and the above goals by which to
137
There will inevitably be people who disagree with my particular
138
choices. Some desire finer control over their markup, others
139
prefer less. Some are concerned with very short docstrings,
140
others with full-length documents. This specification is an
141
effort to provide a reasonably rich set of markup constructs in a
142
reasonably simple form, that should satisfy a reasonably large
143
group of reasonable people.
145
David Goodger (goodger@users.sourceforge.net), 2001-04-20
147
.. _Doc-SIG: http://www.python.org/sigs/doc-sig/
153
reStructuredText_, the specification, is based on StructuredText_ and
154
Setext_. StructuredText was developed by Jim Fulton of `Zope
155
Corporation`_ (formerly Digital Creations) and first released in 1996.
156
It is now released as a part of the open-source "Z Object Publishing
157
Environment" (ZOPE_). Ian Feldman's and Tony Sanders' earlier Setext_
158
specification was either an influence on StructuredText or, by their
159
similarities, at least evidence of the correctness of this approach.
161
I discovered StructuredText_ in late 1999 while searching for a way to
162
document the Python modules in one of my projects. Version 1.1 of
163
StructuredText was included in Daniel Larsson's pythondoc_. Although
164
I was not able to get pythondoc to work for me, I found StructuredText
165
to be almost ideal for my needs. I joined the Python Doc-SIG_
166
(Documentation Special Interest Group) mailing list and found an
167
ongoing discussion of the shortcomings of the StructuredText
168
"standard". This discussion has been going on since the inception of
169
the mailing list in 1996, and possibly predates it.
171
I decided to modify the original module with my own extensions and
172
some suggested by the Doc-SIG members. I soon realized that the
173
module was not written with extension in mind, so I embarked upon a
174
general reworking, including adapting it to the "re" regular
175
expression module (the original inspiration for the name of this
176
project). Soon after I completed the modifications, I discovered that
177
StructuredText.py was up to version 1.23 in the ZOPE distribution.
178
Implementing the new syntax extensions from version 1.23 proved to be
179
an exercise in frustration, as the complexity of the module had become
182
In 2000, development on StructuredTextNG_ ("Next Generation") began at
183
`Zope Corporation`_ (then Digital Creations). It seems to have many
184
improvements, but still suffers from many of the problems of classic
187
I decided that a complete rewrite was in order, and even started a
188
`reStructuredText SourceForge project`_ (now inactive). My
189
motivations (the "itches" I aim to "scratch") are as follows:
191
- I need a standard format for inline documentation of the programs I
192
write. This inline documentation has to be convertible to other
193
useful formats, such as HTML. I believe many others have the same
196
- I believe in the Setext/StructuredText idea and want to help
197
formalize the standard. However, I feel the current specifications
198
and implementations have flaws that desperately need fixing.
200
- reStructuredText could form part of the foundation for a
201
documentation extraction and processing system, greatly benefitting
202
Python. But it is only a part, not the whole. reStructuredText is
203
a markup language specification and a reference parser
204
implementation, but it does not aspire to be the entire system. I
205
don't want reStructuredText or a hypothetical Python documentation
206
processor to die stillborn because of over-ambition.
208
- Most of all, I want to help ease the documentation chore, the bane
209
of many a programmer.
211
Unfortunately I was sidetracked and stopped working on this project.
212
In November 2000 I made the time to enumerate the problems of
213
StructuredText and possible solutions, and complete the first draft of
214
a specification. This first draft was posted to the Doc-SIG in three
217
- `A Plan for Structured Text`__
218
- `Problems With StructuredText`__
219
- `reStructuredText: Revised Structured Text Specification`__
221
__ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html
222
__ http://mail.python.org/pipermail/doc-sig/2000-November/001240.html
223
__ http://mail.python.org/pipermail/doc-sig/2000-November/001241.html
225
In March 2001 a flurry of activity on the Doc-SIG spurred me to
226
further revise and refine my specification, the result of which you
227
are now reading. An offshoot of the reStructuredText project has been
228
the realization that a single markup scheme, no matter how well
229
thought out, may not be enough. In order to tame the endless debates
230
on Doc-SIG, a flexible `Docstring Processing System framework`_ needed
231
to be constructed. This framework has become the more important of
232
the two projects; reStructuredText_ has found its place as one
233
possible choice for a single component of the larger framework.
235
The project web site and the first project release were rolled out in
236
June 2001, including posting the second draft of the spec [#spec-2]_
237
and the first draft of PEPs 256, 257, and 258 [#peps-1]_ to the
238
Doc-SIG. These documents and the project implementation proceeded to
239
evolve at a rapid pace. Implementation history details can be found
240
in the `project history file`_.
242
In November 2001, the reStructuredText parser was nearing completion.
243
Development of the parser continued with the addition of small
244
convenience features, improvements to the syntax, the filling in of
245
gaps, and bug fixes. After a long holiday break, in early 2002 most
246
development moved over to the other Docutils components, the
247
"Readers", "Writers", and "Transforms". A "standalone" reader
248
(processes standalone text file documents) was completed in February,
249
and a basic HTML writer (producing HTML 4.01, using CSS-1) was
250
completed in early March.
252
`PEP 287`_, "reStructuredText Standard Docstring Format", was created
253
to formally propose reStructuredText as a standard format for Python
254
docstrings, PEPs, and other files. It was first posted to
255
comp.lang.python_ and the Python-dev_ mailing list on 2002-04-02.
257
Version 0.4 of the reStructuredText__ and `Docstring Processing
258
System`_ projects were released in April 2002. The two projects were
259
immediately merged, renamed to "Docutils_", and a 0.1 release soon
262
.. __: `reStructuredText SourceForge project`_
264
.. [#spec-2] The second draft of the spec:
266
- `An Introduction to reStructuredText`__
267
- `Problems With StructuredText`__
268
- `reStructuredText Markup Specification`__
269
- `Python Extensions to the reStructuredText Markup
272
__ http://mail.python.org/pipermail/doc-sig/2001-June/001858.html
273
__ http://mail.python.org/pipermail/doc-sig/2001-June/001859.html
274
__ http://mail.python.org/pipermail/doc-sig/2001-June/001860.html
275
__ http://mail.python.org/pipermail/doc-sig/2001-June/001861.html
277
.. [#peps-1] First drafts of the PEPs:
279
- `PEP 256: Docstring Processing System Framework`__
280
- `PEP 258: DPS Generic Implementation Details`__
281
- `PEP 257: Docstring Conventions`__
283
Current working versions of the PEPs can be found in
284
http://docutils.sourceforge.net/docs/peps/, and official versions
285
can be found in the `master PEP repository`_.
287
__ http://mail.python.org/pipermail/doc-sig/2001-June/001855.html
288
__ http://mail.python.org/pipermail/doc-sig/2001-June/001856.html
289
__ http://mail.python.org/pipermail/doc-sig/2001-June/001857.html
292
.. _Zope Corporation: http://www.zope.com
293
.. _ZOPE: http://www.zope.org
294
.. _reStructuredText SourceForge project:
295
http://structuredtext.sourceforge.net/
296
.. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/
297
.. _StructuredTextNG:
298
http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/StructuredTextNG
299
.. _project history file: ../../../HISTORY.html
300
.. _PEP 287: ../../peps/pep-0287.html
301
.. _Docstring Processing System framework: ../../peps/pep-0256.html
302
.. _comp.lang.python: news:comp.lang.python
303
.. _Python-dev: http://mail.python.org/pipermail/python-dev/
304
.. _Docstring Processing System: http://docstring.sourceforge.net/
305
.. _master PEP repository: http://www.python.org/peps/
311
indent-tabs-mode: nil
312
sentence-end-double-space: t
added
removed
docs/ref/rst/introduction.txt
