1
.. This is a comment. Note how any initial comments are moved by
2
transforms to after the document title, subtitle, and docinfo.
4
================================
5
reStructuredText Test Document
6
================================
8
.. Above is the document title, and below is the subtitle.
9
They are transformed from section titles after parsing.
11
--------------------------------
12
Examples of Syntax Constructs
13
--------------------------------
15
.. bibliographic fields (which also require a transform):
17
:Author: David Goodger
18
:Address: 123 Example Street
21
:Contact: goodger@users.sourceforge.net
22
:Authors: Me; Myself; I
23
:organization: humankind
24
:date: $Date: 2004/01/04 17:44:46 $
25
:status: This is a "work in progress"
26
:revision: $Revision: 1.29 $
28
:copyright: This document has been placed in the public domain. You
29
may do with it as you wish. You may copy, modify,
30
redistribute, reattribute, sell, buy, rent, lease,
31
destroy, or improve it, quote it at length, excerpt,
32
incorporate, collate, fold, staple, or mutilate it, or do
33
anything else to it that your or anyone else's heart
35
:field name: This is a generic bibliographic field.
37
Generic bibliographic fields may contain multiple body elements.
43
For Docutils users & co-developers.
47
This is a test document, containing at least one example of each
48
reStructuredText construct.
51
:keywords: reStructuredText, test, parser
52
:description lang=en: A test document, containing at least one
53
example of each reStructuredText construct.
55
.. contents:: Table of Contents
56
.. section-numbering::
65
That's it, the text just above this line.
74
It divides the section.
87
Paragraphs contain text and may contain inline markup: *emphasis*,
88
**strong emphasis**, ``inline literals``, standalone hyperlinks
89
(http://www.python.org), external hyperlinks (Python_), internal
90
cross-references (example_), external hyperlinks with embedded URIs
91
(`Python web site <http://www.python.org>`__), footnote references
92
(manually numbered [1]_, anonymous auto-numbered [#]_, labeled
93
auto-numbered [#label]_, or symbolic [*]_), citation references
94
([CIT2002]_), substitution references (|example|), and _`inline
95
hyperlink targets` (see Targets_ below for a reference back to here).
96
Character-level inline markup is also possible (although exceedingly
97
ugly!) in *re*\ ``Structured``\ *Text*. Problems are indicated by
98
|problematic| text (generated by processing errors; this one is
101
The default role for interpreted text is `Title Reference`. Here are
102
some explicit interpreted text roles: a PEP reference (:PEP:`287`); an
103
RFC reference (:RFC:`2822`); a :sub:`subscript`; a :sup:`superscript`;
104
and explicit roles for :emphasis:`standard` :strong:`inline`
107
.. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
109
Let's test wrapping and whitespace significance in inline literals:
110
``This is an example of --inline-literal --text, --including some--
111
strangely--hyphenated-words. Adjust-the-width-of-your-browser-window
112
to see how the text is wrapped. -- ---- -------- Now note the
113
spacing between the words of this sentence (words
114
should be grouped in pairs).``
116
If the ``--pep-references`` option was supplied, there should be a
117
live link to PEP 258 here.
124
+ Nested bullet list.
129
Paragraph 2 of item 2.
131
* Nested bullet list.
152
2. Lists that don't start at 1:
172
Definition paragraph 1.
174
Definition paragraph 2.
181
:what: Field lists map field names to field bodies, like database
182
records. They are often part of an extension syntax. They are
183
an unambiguous variant of RFC 2822 fields.
187
The field marker is a colon, the field name, and a colon.
189
The field body may contain one or more body elements, indented
190
relative to the field marker.
195
For listing command-line options:
197
-a command-line option "a"
198
-b file options can have arguments
199
and long descriptions
200
--long options can be long also
201
--input=file long options can also have
205
The description can also start on the next line.
207
The description may contain multiple body elements,
208
regardless of where it starts.
210
-x, -y, -z Multiple options are an "option group".
211
-v, --verbose Commonly-seen: short & long options.
212
-1 file, --one=file, --two file
213
Multiple options with arguments.
214
/V DOS/VMS-style options too
216
There must be at least two spaces between the option and the
222
Literal blocks are indicated with a double-colon ("::") at the end of
223
the preceding paragraph (over there ``-->``). They can be indented::
226
text = 'is left as-is'
227
spaces_and_linebreaks = 'are preserved'
228
markup_processing = None
230
Or they can be quoted without indentation::
234
> Why didn't I think of that?
239
Block quotes consist of indented body elements:
241
My theory by A. Elk. Brackets Miss, brackets. This theory goes
242
as follows and begins now. All brontosauruses are thin at one
243
end, much much thicker in the middle and then thin again at the
244
far end. That is my theory, it is mine, and belongs to me and I
245
own it, and what it is too.
252
>>> print 'Python-specific usage examples; begun with ">>>"'
253
Python-specific usage examples; begun with ">>>"
254
>>> print '(cut and pasted from interactive Python sessions)'
255
(cut and pasted from interactive Python sessions)
260
Here's a grid table followed by a simple table:
262
+------------------------+------------+----------+----------+
263
| Header row, column 1 | Header 2 | Header 3 | Header 4 |
264
| (header rows optional) | | | |
265
+========================+============+==========+==========+
266
| body row 1, column 1 | column 2 | column 3 | column 4 |
267
+------------------------+------------+----------+----------+
268
| body row 2 | Cells may span columns. |
269
+------------------------+------------+---------------------+
270
| body row 3 | Cells may | - Table cells |
271
+------------------------+ span rows. | - contain |
272
| body row 4 | | - body elements. |
273
+------------------------+------------+----------+----------+
274
| body row 5 | Cells may also be | |
275
| | empty: ``-->`` | |
276
+------------------------+-----------------------+----------+
292
.. [1] A footnote contains body elements, consistently indented by at
295
This is the footnote's second paragraph.
297
.. [#label] Footnotes may be numbered, either manually (as in [1]_) or
298
automatically using a "#"-prefixed label. This footnote has a
299
label so it can be referred to from multiple places, both as a
300
footnore reference ([#label]_) and as a hyperlink reference
303
.. [#] This footnote is numbered automatically and anonymously using a
306
.. [*] Footnotes may also use symbols, specified with a "*" label.
307
Here's a reference to the next footnote: [*]_.
309
.. [*] This footnote shows the next symbol in the sequence.
311
.. [4] Here's an unreferenced footnote, with a reference to a
312
nonexistent footnote: [5]_.
317
.. [CIT2002] Citations are text-labeled footnotes. They may be
318
rendered separately and differently from footnotes.
320
Here's a reference to the above, [CIT2002]_, and a [nonexistent]_
328
This paragraph is pointed to by the explicit "example" target. A
329
reference can be found under `Inline Markup`_, above. `Inline
330
hyperlink targets`_ are also possible.
332
Section headers are implicit targets, referred to by name. See
333
Targets_, which is a subsection of `Body Elements`_.
335
Explicit external targets are interpolated into references such as
338
.. _Python: http://www.python.org/
340
Targets may be indirect and anonymous. Thus `this phrase`__ may also
341
refer to the Targets_ section.
345
Here's a `hyperlink reference without a target`_, which generates an
348
Duplicate Target Names
349
``````````````````````
351
Duplicate names in section headers or other implicit targets will
352
generate "info" (level-1) system messages. Duplicate names in
353
explicit targets will generate "warning" (level-2) system messages.
355
Duplicate Target Names
356
``````````````````````
358
Since there are two "Duplicate Target Names" section headers, we
359
cannot uniquely refer to either of them by name. If we try to (like
360
this: `Duplicate Target Names`_), an error is generated.
365
.. contents:: :local:
367
These are just a sample of the many reStructuredText Directives. For
368
others, please see http://docutils.sf.net/spec/rst/directives.html.
373
An example of the "contents" directive can be seen above this section
374
(a local, untitled table of contents_) and at the beginning of the
375
document (a document-wide `table of contents`_).
380
An image directive (also clickable -- a hyperlink reference):
382
.. image:: ../docs/rst/images/title.png
387
.. figure:: ../docs/rst/images/title.png
388
:alt: reStructuredText, the markup syntax
390
A figure is an image with a caption and/or a legend:
392
+------------+-----------------------------------------------+
393
| re | Revised, revisited, based on 're' module. |
394
+------------+-----------------------------------------------+
395
| Structured | Structure-enhanced text, structuredtext. |
396
+------------+-----------------------------------------------+
397
| Text | Well it is, isn't it? |
398
+------------+-----------------------------------------------+
400
This paragraph is also part of the legend.
405
.. Attention:: Directives at large.
409
Don't take any wooden nickels.
411
.. DANGER:: Mad scientist at work!
413
.. Error:: Does not compute.
415
.. Hint:: It's bigger than a bread box.
418
- Wash behind your ears.
419
- Clean up your room.
423
.. Note:: This is a note.
425
.. Tip:: 15% if the service is good.
427
.. WARNING:: Strong prose may provoke extreme mental exertion.
428
Reader discretion is strongly advised.
430
.. admonition:: And, by the way...
432
You can make up your own admonition too.
434
Topics, Sidebars, and Rubrics
435
`````````````````````````````
437
.. sidebar:: Sidebar Title
438
:subtitle: Optional Subtitle
440
This is a sidebar. It is for text outside the flow of the main
443
.. rubric:: This is a rubric inside a sidebar
445
Sidebars often appears beside the main text with a border and
448
.. topic:: Topic Title
452
.. rubric:: This is a rubric
462
Take it away, Eric the Orchestra Leader!
466
A one, two, a one two three four
468
Half a bee, philosophically,
469
must, *ipso facto*, half not be.
470
But half the bee has got to be,
471
*vis a vis* its entity. D'you see?
473
But can a bee be said to be
474
or not to be an entire bee,
475
when half the bee is not a bee,
476
due to some ancient injury?
483
I recommend you try |Python|_.
485
.. |Python| replace:: Python, *the* best language around
487
Substitution Definitions
488
------------------------
490
An inline image (|example|) example:
492
.. |EXAMPLE| image:: ../docs/rst/images/biohazard.png
494
(Substitution definitions are not visible in the HTML source.)
501
.. Comments begin with two dots and a space. Anything may
502
follow, except for the syntax of footnotes, hyperlink
503
targets, directives, or substitution definitions.
505
Double-dashes -- "--" -- must be escaped somehow in HTML output.
507
(View the HTML source to see the comment.)
512
Any errors caught during processing will generate system messages.
514
There should be five messages in the following, auto-generated
515
section, "Docutils System Messages":
517
.. section should be added by Docutils automatically
added
removed
tools/test.txt
