1
.. This is a comment. Note how any initial comments are moved by
2
transforms to after the document title, subtitle, and docinfo.
6
================================
7
reStructuredText Test Document
8
================================
10
.. Above is the document title, and below is the subtitle.
11
They are transformed from section titles after parsing.
15
--------------------------------
16
Examples of Syntax Constructs
17
--------------------------------
19
.. bibliographic fields (which also require a transform):
21
:Author: David Goodger
22
:Address: 123 Example Street
25
:Contact: goodger@users.sourceforge.net
26
:Authors: Me; Myself; I
27
:organization: humankind
28
:date: Now, or yesterday. Or maybe even *before* yesterday.
29
:status: This is a "work in progress"
30
:revision: is managed by a version control system.
32
:copyright: This document has been placed in the public domain. You
33
may do with it as you wish. You may copy, modify,
34
redistribute, reattribute, sell, buy, rent, lease,
35
destroy, or improve it, quote it at length, excerpt,
36
incorporate, collate, fold, staple, or mutilate it, or do
37
anything else to it that your or anyone else's heart
39
:field name: This is a "generic bibliographic field".
41
Generic bibliographic fields may contain multiple body elements.
47
For Docutils users & co-developers.
51
This is a test document, containing at least one example of each
52
reStructuredText construct.
55
:keywords: reStructuredText, test, parser
56
:description lang=en: A test document, containing at least one
57
example of each reStructuredText construct.
59
.. contents:: Table of Contents
60
.. section-numbering::
71
That's it, the text just above this line.
83
It divides the section. Transitions may also occur between sections:
98
Paragraphs contain text and may contain inline markup: *emphasis*,
99
**strong emphasis**, ``inline literals``, standalone hyperlinks
100
(http://www.python.org), external hyperlinks (Python_), internal
101
cross-references (example_), external hyperlinks with embedded URIs
102
(`Python web site <http://www.python.org>`__), `anonymous hyperlink
103
references`__ (`a second reference`__), footnote references (manually
104
numbered [1]_, anonymous auto-numbered [#]_, labeled auto-numbered
105
[#label]_, or symbolic [*]_), citation references ([CIT2002]_),
106
substitution references (|example|), and _`inline hyperlink targets`
107
(see Targets_ below for a reference back to here). Character-level
108
inline markup is also possible (although exceedingly ugly!) in *re*\
109
``Structured``\ *Text*. Problems are indicated by |problematic| text
110
(generated by processing errors; this one is intentional). Here is a
111
reference to the doctitle_ and the subtitle_.
113
__ http://www.python.org/
114
__ http://docutils.sourceforge.net/
116
The default role for interpreted text is `Title Reference`. Here are
117
some explicit interpreted text roles: a PEP reference (:PEP:`287`); an
118
RFC reference (:RFC:`2822`); a :sub:`subscript`; a :sup:`superscript`;
119
and explicit roles for :emphasis:`standard` :strong:`inline`
122
.. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
124
Let's test wrapping and whitespace significance in inline literals:
125
``This is an example of --inline-literal --text, --including some--
126
strangely--hyphenated-words. Adjust-the-width-of-your-browser-window
127
to see how the text is wrapped. -- ---- -------- Now note the
128
spacing between the words of this sentence (words
129
should be grouped in pairs).``
131
If the ``--pep-references`` option was supplied, there should be a
132
live link to PEP 258 here.
139
+ Nested bullet list.
144
Paragraph 2 of item 2.
146
* Nested bullet list.
154
* This nested list should be compacted by the HTML writer.
158
.. Even if this item contains a target and a comment.
173
2. Lists that don't start at 1:
193
Definition paragraph 1.
195
Definition paragraph 2.
198
Term : classifier one : classifier two
204
:what: Field lists map field names to field bodies, like database
205
records. They are often part of an extension syntax. They are
206
an unambiguous variant of RFC 2822 fields.
210
The field marker is a colon, the field name, and a colon.
212
The field body may contain one or more body elements, indented
213
relative to the field marker.
219
This paragraph has the `credits` class set. (This is actually not
220
about credits but just for ensuring that the class attribute
221
doesn't get stripped away.)
226
For listing command-line options:
228
-a command-line option "a"
229
-b file options can have arguments
230
and long descriptions
231
--long options can be long also
232
--input=file long options can also have
236
The description can also start on the next line.
238
The description may contain multiple body elements,
239
regardless of where it starts.
241
-x, -y, -z Multiple options are an "option group".
242
-v, --verbose Commonly-seen: short & long options.
243
-1 file, --one=file, --two file
244
Multiple options with arguments.
245
/V DOS/VMS-style options too
247
There must be at least two spaces between the option and the
253
Literal blocks are indicated with a double-colon ("::") at the end of
254
the preceding paragraph (over there ``-->``). They can be indented::
257
text = 'is left as-is'
258
spaces_and_linebreaks = 'are preserved'
259
markup_processing = None
261
Or they can be quoted without indentation::
265
> Why didn't I think of that?
270
This section tests line blocks. Line blocks are body elements which
271
consist of lines and other line blocks. Nested line blocks cause
274
| This is a line block. It ends with a blank line.
275
| New lines begin with a vertical bar ("|").
276
| Line breaks and initial indent are significant, and preserved.
277
| Continuation lines are also possible. A long line that is intended
278
to wrap should begin with a space in place of the vertical bar.
279
| The left edge of a continuation line need not be aligned with
280
the left edge of the text above it.
282
| This is a second line block.
284
| Blank lines are permitted internally, but they must begin with a "|".
286
Another line block, surrounded by paragraphs:
288
| And it's no good waiting by the window
289
| It's no good waiting for the sun
290
| Please believe me, the things you dream of
291
| They don't fall in the lap of no-one
293
Take it away, Eric the Orchestra Leader!
295
| A one, two, a one two three four
297
| Half a bee, philosophically,
298
| must, *ipso facto*, half not be.
299
| But half the bee has got to be,
300
| *vis a vis* its entity. D'you see?
302
| But can a bee be said to be
303
| or not to be an entire bee,
304
| when half the bee is not a bee,
305
| due to some ancient injury?
312
Block quotes consist of indented body elements:
314
My theory by A. Elk. Brackets Miss, brackets. This theory goes
315
as follows and begins now. All brontosauruses are thin at one
316
end, much much thicker in the middle and then thin again at the
317
far end. That is my theory, it is mine, and belongs to me and I
318
own it, and what it is too.
325
>>> print 'Python-specific usage examples; begun with ">>>"'
326
Python-specific usage examples; begun with ">>>"
327
>>> print '(cut and pasted from interactive Python sessions)'
328
(cut and pasted from interactive Python sessions)
333
.. [1] A footnote contains body elements, consistently indented by at
336
This is the footnote's second paragraph.
338
.. [#label] Footnotes may be numbered, either manually (as in [1]_) or
339
automatically using a "#"-prefixed label. This footnote has a
340
label so it can be referred to from multiple places, both as a
341
footnote reference ([#label]_) and as a hyperlink reference
344
.. [#] This footnote is numbered automatically and anonymously using a
347
This is the second paragraph.
349
And this is the third paragraph.
351
.. [*] Footnotes may also use symbols, specified with a "*" label.
352
Here's a reference to the next footnote: [*]_.
354
.. [*] This footnote shows the next symbol in the sequence.
356
.. [4] Here's an unreferenced footnote, with a reference to a
357
nonexistent footnote: [5]_.
362
.. [CIT2002] Citations are text-labeled footnotes. They may be
363
rendered separately and differently from footnotes.
365
Here's a reference to the above, [CIT2002]_, and a [nonexistent]_
375
This paragraph is pointed to by the explicit "example" target. A
376
reference can be found under `Inline Markup`_, above. `Inline
377
hyperlink targets`_ are also possible.
379
Section headers are implicit targets, referred to by name. See
380
Targets_, which is a subsection of `Body Elements`_.
382
Explicit external targets are interpolated into references such as
385
.. _Python: http://www.python.org/
387
Targets may be indirect and anonymous. Thus `this phrase`__ may also
388
refer to the Targets_ section.
392
Here's a `hyperlink reference without a target`_, which generates an
395
Duplicate Target Names
396
``````````````````````
398
Duplicate names in section headers or other implicit targets will
399
generate "info" (level-1) system messages. Duplicate names in
400
explicit targets will generate "warning" (level-2) system messages.
402
Duplicate Target Names
403
``````````````````````
405
Since there are two "Duplicate Target Names" section headers, we
406
cannot uniquely refer to either of them by name. If we try to (like
407
this: `Duplicate Target Names`_), an error is generated.
412
.. contents:: :local:
414
These are just a sample of the many reStructuredText Directives. For
416
http://docutils.sourceforge.net/docs/ref/rst/directives.html.
421
An example of the "contents" directive can be seen above this section
422
(a local, untitled table of contents_) and at the beginning of the
423
document (a document-wide `table of contents`_).
428
An image directive (also clickable -- a hyperlink reference):
430
.. image:: ../../../docs/user/rst/images/title.png
431
:class: class1 class2
434
Image with multiple IDs:
439
.. image:: ../../../docs/user/rst/images/title.png
443
.. image:: ../../../docs/user/rst/images/biohazard.png
446
A left-aligned image:
448
.. image:: ../../../docs/user/rst/images/biohazard.png
451
A right-aligned image:
453
.. image:: ../../../docs/user/rst/images/biohazard.png
458
.. figure:: ../../../docs/user/rst/images/biohazard.png
459
:figclass: figclass1 figclass2
460
:class: class1 class2
461
:alt: reStructuredText, the markup syntax
465
A figure is an image with a caption and/or a legend:
467
+------------+-----------------------------------------------+
468
| re | Revised, revisited, based on 're' module. |
469
+------------+-----------------------------------------------+
470
| Structured | Structure-enhanced text, structuredtext. |
471
+------------+-----------------------------------------------+
472
| Text | Well it is, isn't it? |
473
+------------+-----------------------------------------------+
475
This paragraph is also part of the legend.
477
.. figure:: ../../../docs/user/rst/images/biohazard.png
478
:figclass: figclass1 figclass2
479
:class: class1 class2
480
:alt: reStructuredText, the markup syntax
484
A left-aligned figure.
488
This paragraph might flow around the figure...
492
.. figure:: ../../../docs/user/rst/images/biohazard.png
500
The legend may consist of several paragraphs.
502
This paragraph might flow around the figure...
504
A left-aligned figure:
506
.. figure:: ../../../docs/user/rst/images/biohazard.png
514
The legend may consist of several paragraphs.
516
This paragraph might flow around the figure...
522
.. image:: ../../../docs/user/rst/images/biohazard.png
525
An image 2 em wide and 30 pixel high:
527
.. image:: ../../../docs/user/rst/images/biohazard.png
531
An image occupying 70% of the line width:
533
.. image:: ../../../docs/user/rst/images/biohazard.png
538
.. image:: ../../../docs/user/rst/images/biohazard.png
545
.. Attention:: Directives at large.
549
Don't take any wooden nickels.
551
.. DANGER:: Mad scientist at work!
553
.. Error:: Does not compute.
555
.. Hint:: It's bigger than a bread box.
558
- Wash behind your ears.
559
- Clean up your room.
563
.. Note:: This is a note.
565
.. Tip:: 15% if the service is good.
567
.. WARNING:: Strong prose may provoke extreme mental exertion.
568
Reader discretion is strongly advised.
570
.. admonition:: And, by the way...
572
You can make up your own admonition too.
574
.. _Docutils: http://docutils.sourceforge.net/
576
Topics, Sidebars, and Rubrics
577
`````````````````````````````
579
.. sidebar:: Sidebar Title
580
:subtitle: Optional Subtitle
582
This is a sidebar. It is for text outside the flow of the main
585
.. rubric:: This is a rubric inside a sidebar
587
Sidebars often appears beside the main text with a border and
590
.. topic:: Topic Title
594
.. rubric:: This is a rubric
605
I recommend you try |Python|_.
607
.. |Python| replace:: Python, *the* best language around
615
Compound 1, paragraph 1.
617
Compound 1, paragraph 2.
619
* Compound 1, list item one.
620
* Compound 1, list item two.
622
Another compound statement:
626
Compound 2, a literal block::
630
Compound 2, this is a test.
634
Compound 3, only consisting of one paragraph.
641
This one starts with a literal block.
643
Compound 4, a paragraph.
645
Now something *really* perverted -- a nested compound block. This is
646
just to test that it works at all; the results don't have to be
651
Compound 5, block 1 (a paragraph).
655
Compound 6, block 2 in compound 5.
657
Compound 6, another paragraph.
659
Compound 5, block 3 (a paragraph).
663
Compound 7, with a table inside:
665
+--------------------+--------------------+--------------------+
666
| Left cell, first | Middle cell, | Right cell. |
667
| paragraph. | consisting of | |
668
| | exactly one | Paragraph 2. |
669
| Left cell, second | paragraph. | |
670
| paragraph. | | Paragraph 3. |
671
+--------------------+--------------------+--------------------+
673
Compound 7, a paragraph after the table.
675
Compound 7, another paragraph.
677
Parsed Literal Blocks
678
`````````````````````
682
This is a parsed literal block.
683
This line is indented. The next line is blank.
685
Inline markup is supported, e.g. *emphasis*, **strong**, ``literal
686
text``, footnotes [1]_, _`targets`, and `references
687
<http://www.python.org/>`_.
689
Substitution Definitions
690
------------------------
692
An inline image (|example|) example:
694
.. |EXAMPLE| image:: ../../../docs/user/rst/images/biohazard.png
696
(Substitution definitions are not visible in the HTML source.)
703
.. Comments begin with two dots and a space. Anything may
704
follow, except for the syntax of footnotes, hyperlink
705
targets, directives, or substitution definitions.
707
Double-dashes -- "--" -- must be escaped somehow in HTML output.
709
(View the HTML source to see the comment.)
714
This does not necessarily look nice, because there may be missing white space.
716
It's just there to freeze the behavior.
730
Another test with myclass set.
732
.. role:: raw-role(raw)
734
:class: myrawroleclass
736
This is the :raw-role:`fourth test` with myrawroleclass set.
740
Fifth test in HTML.<br />Line two.
744
Fifth test in LaTeX.\\Line two.
749
.. container:: custom
added
removed
test/functional/input/data/standard.txt
