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: 2021-03-09 13:53:57 +0100 (Di, 09. Mär 2021) $ 25:status: This is a "work in progress" 26:revision: $Revision: 8632 $ 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 61Structural Elements 62=================== 63 64Section Title 65------------- 66 67That's it, the text just above this line. 68 69Transitions 70----------- 71 72Here's a transition: 73 74--------- 75 76It divides the section. 77 78Body Elements 79============= 80 81Paragraphs 82---------- 83 84A paragraph. 85 86Inline Markup 87````````````` 88 89Paragraphs contain text and may contain inline markup: *emphasis*, 90**strong emphasis**, ``inline literals``, standalone hyperlinks 91(http://www.python.org), external hyperlinks (Python_), internal 92cross-references (example_), external hyperlinks with embedded URIs 93(`Python web site <http://www.python.org>`__), footnote references 94(manually numbered [1]_, anonymous auto-numbered [#]_, labeled 95auto-numbered [#label]_, or symbolic [*]_), citation references 96([CIT2002]_), substitution references (|example|), and _`inline 97hyperlink targets` (see Targets_ below for a reference back to here). 98Character-level inline markup is also possible (although exceedingly 99ugly!) in *re*\ ``Structured``\ *Text*. Problems are indicated by 100|problematic| text (generated by processing errors; this one is 101intentional). 102 103The default role for interpreted text is `Title Reference`. Here are 104some explicit interpreted text roles: a PEP reference (:PEP:`287`); an 105RFC reference (:RFC:`2822`); a :sub:`subscript`; a :sup:`superscript`; 106and explicit roles for :emphasis:`standard` :strong:`inline` 107:literal:`markup`. 108 109.. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! 110 111Let's test wrapping and whitespace significance in inline literals: 112``This is an example of --inline-literal --text, --including some-- 113strangely--hyphenated-words. Adjust-the-width-of-your-browser-window 114to see how the text is wrapped. -- ---- -------- Now note the 115spacing between the words of this sentence (words 116should be grouped in pairs).`` 117 118If the ``--pep-references`` option was supplied, there should be a 119live link to PEP 258 here. 120 121Bullet 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 141Enumerated Lists 142---------------- 143 1441. Arabic numerals. 145 146 a) lower alpha) 147 148 (i) (lower roman) 149 150 A. upper alpha. 151 152 I) upper roman) 153 1542. 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 170Definition Lists 171---------------- 172 173Term 174 Definition 175Term : classifier 176 Definition paragraph 1. 177 178 Definition paragraph 2. 179Term 180 Definition 181 182Field 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 196Option Lists 197------------ 198 199For 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 220There must be at least two spaces between the option and the 221description. 222 223Literal Blocks 224-------------- 225 226Literal blocks are indicated with a double-colon ("::") at the end of 227the 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 234Or they can be quoted without indentation:: 235 236>> Great idea! 237> 238> Why didn't I think of that? 239 240Line 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 255Take 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 271Block Quotes 272------------ 273 274Block 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 284Doctest Blocks 285-------------- 286 287>>> print 'Python-specific usage examples; begun with ">>>"' 288Python-specific usage examples; begun with ">>>" 289>>> print '(cut and pasted from interactive Python sessions)' 290(cut and pasted from interactive Python sessions) 291 292Tables 293------ 294 295Here'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===== ===== ====== 318False False False 319True False True 320False True True 321True True True 322===== ===== ====== 323 324Footnotes 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 349Citations 350--------- 351 352.. [CIT2002] Citations are text-labeled footnotes. They may be 353 rendered separately and differently from footnotes. 354 355Here's a reference to the above, [CIT2002]_, and a [nonexistent]_ 356citation. 357 358Targets 359------- 360 361.. _example: 362 363This paragraph is pointed to by the explicit "example" target. A 364reference can be found under `Inline Markup`_, above. `Inline 365hyperlink targets`_ are also possible. 366 367Section headers are implicit targets, referred to by name. See 368Targets_, which is a subsection of `Body Elements`_. 369 370Explicit external targets are interpolated into references such as 371"Python_". 372 373.. _Python: http://www.python.org/ 374 375Targets may be indirect and anonymous. Thus `this phrase`__ may also 376refer to the Targets_ section. 377 378__ Targets_ 379 380Here's a `hyperlink reference without a target`_, which generates an 381error. 382 383Duplicate Target Names 384`````````````````````` 385 386Duplicate names in section headers or other implicit targets will 387generate "info" (level-1) system messages. Duplicate names in 388explicit targets will generate "warning" (level-2) system messages. 389 390Duplicate Target Names 391`````````````````````` 392 393Since there are two "Duplicate Target Names" section headers, we 394cannot uniquely refer to either of them by name. If we try to (like 395this: `Duplicate Target Names`_), an error is generated. 396 397Directives 398---------- 399 400.. contents:: :local: 401 402These are just a sample of the many reStructuredText Directives. For 403others, please see 404http://docutils.sourceforge.net/docs/ref/rst/directives.html. 405 406Document Parts 407`````````````` 408 409An example of the "contents" directive can be seen above this section 410(a local, untitled table of contents_) and at the beginning of the 411document (a document-wide `table of contents`_). 412 413Images 414`````` 415 416An image directive (also clickable -- a hyperlink reference): 417 418.. image:: images/title.png 419 :target: directives_ 420 421A 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 438Admonitions 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 470Topics, 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 490Target Footnotes 491```````````````` 492 493.. target-notes:: 494 495Replacement Text 496```````````````` 497 498I recommend you try |Python|_. 499 500.. |Python| replace:: Python, *the* best language around 501 502Compound 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 517This construct is called a *compound paragraph* and can be produced 518with the "compound" directive. 519 520Meta 521```` 522 523The `“meta” directive`__ is used to specify metadata to be stored in, 524e.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 535Substitution Definitions 536------------------------ 537 538An inline image (|example|) example: 539 540.. |EXAMPLE| image:: images/biohazard.png 541 542(Substitution definitions are not visible in the HTML source.) 543 544Comments 545-------- 546 547Here'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 557Error Handling 558============== 559 560Any errors caught during processing will generate system messages. 561 562|*** Expect 6 errors (including this one). ***| 563 564There should be six messages in the following, auto-generated 565section, "Docutils System Messages": 566 567.. section should be added by Docutils automatically 568
