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
25 :status: This is a "work in progress"
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**, `interpreted text`, ``inline literals``,
89 standalone hyperlinks (http://www.python.org), external hyperlinks
90 (Python_), internal cross-references (example_), footnote references
91 (manually numbered [1]_, anonymous auto-numbered [#]_, labeled
92 auto-numbered [#label]_, or symbolic [*]_), citation references
93 ([CIT2002]_), substitution references (|example|), and _`inline
94 hyperlink targets` (see Targets_ below for a reference back to here).
95 Problems are indicated by |problematic| text (generated by processing
96 errors; this one is intentional).
98 .. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
100 Let's test wrapping and whitespace significance in inline literals:
101 ``This is an example of --inline-literal --text, --including some--
102 strangely--hyphenated-words. Adjust-the-width-of-your-browser-window
103 to see how the text is wrapped. -- ---- -------- Now note the
104 spacing between the words of this sentence (words
105 should be grouped in pairs).``
107 If the ``--pep-references`` option was supplied, there should be a
108 live link to PEP 258 here.
115 + Nested bullet list.
120 Paragraph 2 of item 2.
122 * Nested bullet list.
143 2. Lists that don't start at 1:
163 Definition paragraph 1.
165 Definition paragraph 2.
172 :what: Field lists map field names to field bodies, like database
173 records. They are often part of an extension syntax. They are
174 an unambiguous variant of RFC 2822 fields.
178 The field marker is a colon, the field name, and a colon.
180 The field body may contain one or more body elements, indented
181 relative to the field marker.
186 For listing command-line options:
188 -a command-line option "a"
189 -b file options can have arguments
190 and long descriptions
191 --long options can be long also
192 --input=file long options can also have
196 The description can also start on the next line.
198 The description may contain multiple body elements,
199 regardless of where it starts.
201 -x, -y, -z Multiple options are an "option group".
202 -v, --verbose Commonly-seen: short & long options.
203 -1 file, --one=file, --two file
204 Multiple options with arguments.
205 /V DOS/VMS-style options too
207 There must be at least two spaces between the option and the
213 Literal blocks are indented, and indicated with a double-colon ("::")
214 at the end of the preceding paragraph (right here ``-->``)::
217 text = 'is left as-is'
218 spaces_and_linebreaks = 'are preserved'
219 markup_processing = None
224 Block quotes consist of indented body elements:
226 This theory, that is mine, is mine.
233 >>> print 'Python-specific usage examples; begun with ">>>"'
234 Python-specific usage examples; begun with ">>>"
235 >>> print '(cut and pasted from interactive Python sessions)'
236 (cut and pasted from interactive Python sessions)
241 Here's a grid table followed by a simple table:
243 +------------------------+------------+----------+----------+
244 | Header row, column 1 | Header 2 | Header 3 | Header 4 |
245 | (header rows optional) | | | |
246 +========================+============+==========+==========+
247 | body row 1, column 1 | column 2 | column 3 | column 4 |
248 +------------------------+------------+----------+----------+
249 | body row 2 | Cells may span columns. |
250 +------------------------+------------+----------+----------+
251 | body row 5 | Cells may also be | |
252 | | empty: ``-->`` | |
253 +------------------------+-----------------------+----------+
256 +------------------------+------------+---------------------+
257 | body row 3 | Cells may | - Table cells |
258 +------------------------+ span rows. | - contain |
259 | body row 4 | | - body elements. |
276 .. [1] A footnote contains body elements, consistently indented by at
279 This is the footnote's second paragraph.
281 .. [#label] Footnotes may be numbered, either manually (as in [1]_) or
282 automatically using a "#"-prefixed label. This footnote has a
283 label so it can be referred to from multiple places, both as a
284 footnore reference ([#label]_) and as a hyperlink reference
287 .. [#] This footnote is numbered automatically and anonymously using a
290 .. [*] Footnotes may also use symbols, specified with a "*" label.
291 Here's a reference to the next footnote: [*]_.
293 .. [*] This footnote shows the next symbol in the sequence.
295 .. [4] Here's an unreferenced footnote, with a reference to a
296 nonexistent footnote: [5]_.
301 .. [CIT2002] Citations are text-labeled footnotes. They may be
302 rendered separately and differently from footnotes.
304 Here's a reference to the above, [CIT2002]_, and a [nonexistent]_
312 This paragraph is pointed to by the explicit "example" target. A
313 reference can be found under `Inline Markup`_, above. `Inline
314 hyperlink targets`_ are also possible.
316 Section headers are implicit targets, referred to by name. See
317 Targets_, which is a subsection of `Body Elements`_.
319 Explicit external targets are interpolated into references such as
322 .. _Python: http://www.python.org/
324 Targets may be indirect and anonymous. Thus `this phrase`__ may also
325 refer to the Targets_ section.
329 Here's a `hyperlink reference without a target`_, which generates an
332 Duplicate Target Names
333 ``````````````````````
335 Duplicate names in section headers or other implicit targets will
336 generate "info" (level-1) system messages. Duplicate names in
337 explicit targets will generate "warning" (level-2) system messages.
339 Duplicate Target Names
340 ``````````````````````
342 Since there are two "Duplicate Target Names" section headers, we
343 cannot uniquely refer to either of them by name. If we try to (like
344 this: `Duplicate Target Names`_), an error is generated.
349 .. contents:: :local:
351 These are just a sample of the many reStructuredText Directives. For
352 others, please see http://docutils.sf.net/spec/rst/directives.html.
357 An example of the "contents" directive can be seen above this section
358 (a local, untitled table of contents_) and at the beginning of the
359 document (a document-wide `table of contents`_).
366 .. image:: ../docs/rst/images/title.png
370 .. figure:: ../docs/rst/images/title.png
371 :alt: reStructuredText, the markup syntax
373 A figure is an image with a caption and/or a legend:
375 +------------+-----------------------------------------------+
376 | re | Revised, revisited, based on 're' module. |
377 +------------+-----------------------------------------------+
378 | Structured | Structure-enhanced text, structuredtext. |
379 +------------+-----------------------------------------------+
380 | Text | Well it is, isn't it? |
381 +------------+-----------------------------------------------+
383 This paragraph is also part of the legend.
388 .. Attention:: Directives at large.
392 Don't take any wooden nickels.
394 .. DANGER:: Mad scientist at work!
396 .. Error:: Does not compute.
398 .. Hint:: It's bigger than a bread box.
401 - Wash behind your ears.
402 - Clean up your room.
406 .. Note:: This is a note.
408 .. Tip:: 15% if the service is good.
410 .. WARNING:: Strong prose may provoke extreme mental exertion.
411 Reader discretion is strongly advised.
421 Take it away, Eric the Orchestra Leader!
425 A one, two, a one two three four
427 Half a bee, philosophically,
428 must, *ipso facto*, half not be.
429 But half the bee has got to be,
430 *vis a vis* its entity. D'you see?
432 But can a bee be said to be
433 or not to be an entire bee,
434 when half the bee is not a bee,
435 due to some ancient injury?
442 I recommend you try |Python|_.
444 .. |Python| replace:: Python, *the* best language around
446 Substitution Definitions
447 ------------------------
449 An inline image (|example|) example:
451 .. |EXAMPLE| image:: ../docs/rst/images/biohazard.png
453 (Substitution definitions are not visible in the HTML source.)
460 .. Comments begin with two dots and a space. Anything may
461 follow, except for the syntax of footnotes, hyperlink
462 targets, directives, or substitution definitions.
464 Double-dashes -- "--" -- must be escaped somehow in HTML output.
466 (View the HTML source to see the comment.)
471 Any errors caught during processing will generate system messages.
473 There should be five messages in the following, auto-generated
474 section, "Docutils System Messages":
476 .. section should be added by Docutils automatically