docutils/docs/user/rst/demo.txt

   1 .. This is a comment. Note how any initial comments are moved by
   2    transforms to after the document title, subtitle, and docinfo.
   3
   4 ================================
   5  reStructuredText Demonstration
   6 ================================
   7
   8 .. Above is the document title, and below is the subtitle.
   9    They are transformed from section titles after parsing.
  10
  11 --------------------------------
  12  Examples of Syntax Constructs
  13 --------------------------------
  14
  15 .. bibliographic fields (which also require a transform):
  16
  17 :Author: David Goodger
  18 :Address: 123 Example Street
  19           Example, EX  Canada
  20           A1B 2C3
  21 :Contact: docutils-develop@lists.sourceforge.net
  22 :Authors: Me; Myself; I
  23 :organization: humankind
  24 :date: $Date$
  25 :status: This is a "work in progress"
  26 :revision: $Revision$
  27 :version: 1
  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
  34             desires.
  35 :field name: This is a generic bibliographic field.
  36 :field name 2:
  37     Generic bibliographic fields may contain multiple body elements.
  38
  39     Like this.
  40
  41 :Dedication:
  42
  43     For Docutils users & co-developers.
  44
  45 :abstract:
  46
  47     This document is a demonstration of the reStructuredText markup
  48     language, containing examples of all basic reStructuredText
  49     constructs and many advanced constructs.
  50
  51 .. meta::
  52    :keywords: reStructuredText, demonstration, demo, parser
  53    :description lang=en: A demonstration of the reStructuredText
  54        markup language, containing examples of all basic
  55        constructs and many advanced constructs.
  56
  57 .. contents:: Table of Contents
  58 .. section-numbering::
  59
  60
  61 Structural Elements
  62 ===================
  63
  64 Section Title
  65 -------------
  66
  67 That's it, the text just above this line.
  68
  69 Transitions
  70 -----------
  71
  72 Here's a transition:
  73
  74 ---------
  75
  76 It divides the section.
  77
  78 Body Elements
  79 =============
  80
  81 Paragraphs
  82 ----------
  83
  84 A paragraph.
  85
  86 Inline Markup
  87 `````````````
  88
  89 Paragraphs contain text and may contain inline markup: *emphasis*,
  90 **strong emphasis**, ``inline literals``, standalone hyperlinks
  91 (https://www.python.org), external hyperlinks (Python_), internal
  92 cross-references (example_), external hyperlinks with embedded URIs
  93 (`Python web site <https://www.python.org>`__), footnote references
  94 (manually numbered [1]_, anonymous auto-numbered [#]_, labeled
  95 auto-numbered [#label]_, or symbolic [*]_), citation references
  96 ([CIT2002]_), substitution references (|example|), and _`inline
  97 hyperlink targets` (see Targets_ below for a reference back to here).
  98 Character-level inline markup is also possible (although exceedingly
  99 ugly!) in *re*\ ``Structured``\ *Text*.  Problems are indicated by
 100 |problematic| text (generated by processing errors; this one is
 101 intentional).
 102
 103 The default role for interpreted text is `Title Reference`.  Here are
 104 some explicit interpreted text roles: a PEP reference (:PEP:`287`); an
 105 RFC reference (:RFC:`2822`); a :sub:`subscript`; a :sup:`superscript`;
 106 and explicit roles for :emphasis:`standard` :strong:`inline`
 107 :literal:`markup`.
 108
 109 .. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
 110
 111 Let's test wrapping and whitespace significance in inline literals:
 112 ``This is an example of --inline-literal --text, --including some--
 113 strangely--hyphenated-words.  Adjust-the-width-of-your-browser-window
 114 to see how the text is wrapped.  -- ---- --------  Now note    the
 115 spacing    between the    words of    this sentence    (words
 116 should    be grouped    in pairs).``
 117
 118 If the ``--pep-references`` option was supplied, there should be a
 119 live link to PEP 258 here.
 120
 121 Bullet Lists
 122 ------------
 123
 124 - A bullet list
 125
 126   + Nested bullet list.
 127   + Nested item 2.
 128
 129 - Item 2.
 130
 131   Paragraph 2 of item 2.
 132
 133   * Nested bullet list.
 134   * Nested item 2.
 135
 136     - Third level.
 137     - Item 2.
 138
 139   * Nested item 3.
 140
 141 Enumerated Lists
 142 ----------------
 143
 144 1. Arabic numerals.
 145
 146    a) lower alpha)
 147
 148       (i) (lower roman)
 149
 150           A. upper alpha.
 151
 152              I) upper roman)
 153
 154 2. Lists that don't start at 1:
 155
 156    3. Three
 157
 158    4. Four
 159
 160    C. C
 161
 162    D. D
 163
 164    iii. iii
 165
 166    iv. iv
 167
 168 #. List items may also be auto-enumerated.
 169
 170 Definition Lists
 171 ----------------
 172
 173 Term
 174     Definition
 175 Term : classifier
 176     Definition paragraph 1.
 177
 178     Definition paragraph 2.
 179 Term
 180     Definition
 181
 182 Field Lists
 183 -----------
 184
 185 :what: Field lists map field names to field bodies, like database
 186        records.  They are often part of an extension syntax.  They are
 187        an unambiguous variant of RFC 2822 fields.
 188
 189 :how arg1 arg2:
 190
 191     The field marker is a colon, the field name, and a colon.
 192
 193     The field body may contain one or more body elements, indented
 194     relative to the field marker.
 195
 196 Option Lists
 197 ------------
 198
 199 For listing command-line options:
 200
 201 -a            command-line option "a"
 202 -b file       options can have arguments
 203               and long descriptions
 204 --long        options can be long also
 205 --input=file  long options can also have
 206               arguments
 207
 208 --very-long-option
 209               The description can also start on the next line.
 210
 211               The description may contain multiple body elements,
 212               regardless of where it starts.
 213
 214 -x, -y, -z    Multiple options are an "option group".
 215 -v, --verbose  Commonly-seen: short & long options.
 216 -1 file, --one=file, --two file
 217               Multiple options with arguments.
 218 /V            DOS/VMS-style options too
 219
 220 There must be at least two spaces between the option and the
 221 description.
 222
 223 Literal Blocks
 224 --------------
 225
 226 Literal blocks are indicated with a double-colon ("::") at the end of
 227 the preceding paragraph (over there ``-->``).  They can be indented::
 228
 229     if literal_block:
 230         text = 'is left as-is'
 231         spaces_and_linebreaks = 'are preserved'
 232         markup_processing = None
 233
 234 Or they can be quoted without indentation::
 235
 236 >> Great idea!
 237 >
 238 > Why didn't I think of that?
 239
 240 Line Blocks
 241 -----------
 242
 243 | This is a line block.  It ends with a blank line.
 244 |     Each new line begins with a vertical bar ("|").
 245 |     Line breaks and initial indents are preserved.
 246 | Continuation lines are wrapped portions of long lines;
 247   they begin with a space in place of the vertical bar.
 248 |     The left edge of a continuation line need not be aligned with
 249   the left edge of the text above it.
 250
 251 | This is a second line block.
 252 |
 253 | Blank lines are permitted internally, but they must begin with a "|".
 254
 255 Take it away, Eric the Orchestra Leader!
 256
 257     | A one, two, a one two three four
 258     |
 259     | Half a bee, philosophically,
 260     |     must, *ipso facto*, half not be.
 261     | But half the bee has got to be,
 262     |     *vis a vis* its entity.  D'you see?
 263     |
 264     | But can a bee be said to be
 265     |     or not to be an entire bee,
 266     |         when half the bee is not a bee,
 267     |             due to some ancient injury?
 268     |
 269     | Singing...
 270
 271 Block Quotes
 272 ------------
 273
 274 Block quotes consist of indented body elements:
 275
 276     My theory by A. Elk.  Brackets Miss, brackets.  This theory goes
 277     as follows and begins now.  All brontosauruses are thin at one
 278     end, much much thicker in the middle and then thin again at the
 279     far end.  That is my theory, it is mine, and belongs to me and I
 280     own it, and what it is too.
 281
 282     -- Anne Elk (Miss)
 283
 284 Doctest Blocks
 285 --------------
 286
 287 >>> print 'Python-specific usage examples; begun with ">>>"'
 288 Python-specific usage examples; begun with ">>>"
 289 >>> print '(cut and pasted from interactive Python sessions)'
 290 (cut and pasted from interactive Python sessions)
 291
 292 Tables
 293 ------
 294
 295 Here's a grid table followed by a simple table:
 296
 297 +------------------------+------------+----------+----------+
 298 | Header row, column 1   | Header 2   | Header 3 | Header 4 |
 299 | (header rows optional) |            |          |          |
 300 +========================+============+==========+==========+
 301 | body row 1, column 1   | column 2   | column 3 | column 4 |
 302 +------------------------+------------+----------+----------+
 303 | body row 2             | Cells may span columns.          |
 304 +------------------------+------------+---------------------+
 305 | body row 3             | Cells may  | - Table cells       |
 306 +------------------------+ span rows. | - contain           |
 307 | body row 4             |            | - body elements.    |
 308 +------------------------+------------+----------+----------+
 309 | body row 5             | Cells may also be     |          |
 310 |                        | empty: ``-->``        |          |
 311 +------------------------+-----------------------+----------+
 312
 313 =====  =====  ======
 314    Inputs     Output
 315 ------------  ------
 316   A      B    A or B
 317 =====  =====  ======
 318 False  False  False
 319 True   False  True
 320 False  True   True
 321 True   True   True
 322 =====  =====  ======
 323
 324 Footnotes
 325 ---------
 326
 327 .. [1] A footnote contains body elements, consistently indented by at
 328    least 3 spaces.
 329
 330    This is the footnote's second paragraph.
 331
 332 .. [#label] Footnotes may be numbered, either manually (as in [1]_) or
 333    automatically using a "#"-prefixed label.  This footnote has a
 334    label so it can be referred to from multiple places, both as a
 335    footnote reference ([#label]_) and as a hyperlink reference
 336    (label_).
 337
 338 .. [#] This footnote is numbered automatically and anonymously using a
 339    label of "#" only.
 340
 341 .. [*] Footnotes may also use symbols, specified with a "*" label.
 342    Here's a reference to the next footnote: [*]_.
 343
 344 .. [*] This footnote shows the next symbol in the sequence.
 345
 346 .. [4] Here's an unreferenced footnote, with a reference to a
 347    nonexistent footnote: [5]_.
 348
 349 Citations
 350 ---------
 351
 352 .. [CIT2002] Citations are text-labeled footnotes. They may be
 353    rendered separately and differently from footnotes.
 354
 355 Here's a reference to the above, [CIT2002]_, and a [nonexistent]_
 356 citation.
 357
 358 Targets
 359 -------
 360
 361 .. _example:
 362
 363 This paragraph is pointed to by the explicit "example" target. A
 364 reference can be found under `Inline Markup`_, above. `Inline
 365 hyperlink targets`_ are also possible.
 366
 367 Section headers are implicit targets, referred to by name. See
 368 Targets_, which is a subsection of `Body Elements`_.
 369
 370 Explicit external targets are interpolated into references such as
 371 "Python_".
 372
 373 .. _Python: https://www.python.org
 374
 375 Targets may be indirect and anonymous.  Thus `this phrase`__ may also
 376 refer to the Targets_ section.
 377
 378 __ Targets_
 379
 380 Here's a `hyperlink reference without a target`_, which generates an
 381 error.
 382
 383 Duplicate Target Names
 384 ``````````````````````
 385
 386 Duplicate names in section headers or other implicit targets will
 387 generate "info" (level-1) system messages.  Duplicate names in
 388 explicit targets will generate "warning" (level-2) system messages.
 389
 390 Duplicate Target Names
 391 ``````````````````````
 392
 393 Since there are two "Duplicate Target Names" section headers, we
 394 cannot uniquely refer to either of them by name.  If we try to (like
 395 this: `Duplicate Target Names`_), an error is generated.
 396
 397 Directives
 398 ----------
 399
 400 .. contents:: :local:
 401
 402 These are just a sample of the many reStructuredText Directives.  For
 403 others, please see
 404 https://docutils.sourceforge.io/docs/ref/rst/directives.html.
 405
 406 Document Parts
 407 ``````````````
 408
 409 An example of the "contents" directive can be seen above this section
 410 (a local, untitled table of contents_) and at the beginning of the
 411 document (a document-wide `table of contents`_).
 412
 413 Images
 414 ``````
 415
 416 An image directive (also clickable -- a hyperlink reference):
 417
 418 .. image:: images/title.png
 419    :target: directives_
 420
 421 A figure directive:
 422
 423 .. figure:: images/title.png
 424    :alt: reStructuredText, the markup syntax
 425
 426    A figure is an image with a caption and/or a legend:
 427
 428    +------------+-----------------------------------------------+
 429    | re         | Revised, revisited, based on 're' module.     |
 430    +------------+-----------------------------------------------+
 431    | Structured | Structure-enhanced text, structuredtext.      |
 432    +------------+-----------------------------------------------+
 433    | Text       | Well it is, isn't it?                         |
 434    +------------+-----------------------------------------------+
 435
 436    This paragraph is also part of the legend.
 437
 438 Admonitions
 439 ```````````
 440
 441 .. Attention:: Directives at large.
 442
 443 .. Caution::
 444
 445    Don't take any wooden nickels.
 446
 447 .. DANGER:: Mad scientist at work!
 448
 449 .. Error:: Does not compute.
 450
 451 .. Hint:: It's bigger than a bread box.
 452
 453 .. Important::
 454    - Wash behind your ears.
 455    - Clean up your room.
 456    - Call your mother.
 457    - Back up your data.
 458
 459 .. Note:: This is a note.
 460
 461 .. Tip:: 15% if the service is good.
 462
 463 .. WARNING:: Strong prose may provoke extreme mental exertion.
 464    Reader discretion is strongly advised.
 465
 466 .. admonition:: And, by the way...
 467
 468    You can make up your own admonition too.
 469
 470 Topics, Sidebars, and Rubrics
 471 `````````````````````````````
 472
 473 .. sidebar:: Optional Sidebar Title
 474    :subtitle: Optional Subtitle
 475
 476    This is a sidebar.  It is for text outside the flow of the main
 477    text.
 478
 479    .. rubric:: This is a rubric inside a sidebar
 480
 481    Sidebars often appears beside the main text with a border and
 482    background color.
 483
 484 .. topic:: Topic Title
 485
 486    This is a topic.
 487
 488 .. rubric:: This is a rubric
 489
 490 Target Footnotes
 491 ````````````````
 492
 493 .. target-notes::
 494
 495 Replacement Text
 496 ````````````````
 497
 498 I recommend you try |Python|_.
 499
 500 .. |Python| replace:: Python, *the* best language around
 501
 502 Compound Paragraph
 503 ``````````````````
 504
 505 .. compound::
 506
 507    This paragraph contains a literal block::
 508
 509        Connecting... OK
 510        Transmitting data... OK
 511        Disconnecting... OK
 512
 513    and thus consists of a simple paragraph, a literal block, and
 514    another simple paragraph.  Nonetheless it is semantically *one*
 515    paragraph.
 516
 517 This construct is called a *compound paragraph* and can be produced
 518 with the "compound" directive.
 519
 520 Meta
 521 ````
 522
 523 The `“meta” directive`__ is used to specify metadata to be stored in,
 524 e.g., HTML META__ tags or ODT file properties.
 525
 526 .. meta::
 527    :keywords: reStructuredText, test, parser
 528    :description lang=en: A test document, containing at least one
 529        example of each reStructuredText construct.
 530
 531 __ https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata
 532 __ https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag
 533
 534
 535 Substitution Definitions
 536 ------------------------
 537
 538 An inline image (|example|) example:
 539
 540 .. |EXAMPLE| image:: images/biohazard.png
 541
 542 (Substitution definitions are not visible in the HTML source.)
 543
 544 Comments
 545 --------
 546
 547 Here's one:
 548
 549 .. Comments begin with two dots and a space. Anything may
 550    follow, except for the syntax of footnotes, hyperlink
 551    targets, directives, or substitution definitions.
 552
 553    Double-dashes -- "--" -- must be escaped somehow in HTML output.
 554
 555 (View the HTML source to see the comment.)
 556
 557 Error Handling
 558 ==============
 559
 560 Any errors caught during processing will generate system messages.
 561
 562 |*** Expect 6 errors (including this one). ***|
 563
 564 There should be six messages in the following, auto-generated
 565 section, "Docutils System Messages":
 566
 567 .. section should be added by Docutils automatically