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.. _doctitle: 5 6================================ 7 reStructuredText Test Document 8================================ 9 10.. Above is the document title, and below is the subtitle. 11 They are transformed from section titles after parsing. 12 13.. _subtitle: 14 15-------------------------------- 16 Examples of Syntax Constructs 17-------------------------------- 18 19.. bibliographic fields (which also require a transform): 20 21:Author: David Goodger 22:Address: 123 Example Street 23 Example, EX Canada 24 A1B 2C3 25:Contact: goodger@python.org 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. 31:version: 1 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 38 desires. 39:field name: This is a "generic bibliographic field". 40:field name "2": 41 Generic bibliographic fields may contain multiple body elements. 42 43 Like this. 44 45:Dedication: 46 47 For Docutils users & co-developers. 48 49:abstract: 50 51 This is a test document, containing at least one example of each 52 reStructuredText construct. 53 54.. raw:: latex 55 56 \pagebreak[4] % start ToC on new page 57 58.. contents:: Table of Contents 59.. section-numbering:: 60 61 62Structural Elements 63=================== 64 65Section Title 66------------- 67Section Subtitle 68```````````````` 69 70Lone subsections are converted to a section subtitle by a transform 71activated with the ``--section-subtitles`` command line option or the 72``sectsubtitle-xform`` configuration value. 73 74Empty Section 75------------- 76 77Transitions 78----------- 79 80Here's a transition: 81 82--------- 83 84It divides the section. Transitions may also occur between sections: 85 86--------- 87 88Body Elements 89============= 90 91Paragraphs 92---------- 93 94A paragraph. 95 96Inline Markup 97````````````` 98 99Paragraphs contain text and may contain inline markup: *emphasis*, 100**strong emphasis**, ``inline literals``, standalone hyperlinks 101(http://www.python.org), external hyperlinks (Python_), internal 102cross-references (example_), external hyperlinks with embedded URIs 103(`Python web site <http://www.python.org>`__), `anonymous hyperlink 104references`__ (`a second reference`__), footnote references (manually 105numbered [1]_, anonymous auto-numbered [#]_, labeled auto-numbered 106[#label]_, or symbolic [*]_), citation references (see [CIT2002]_), 107substitution references (|example| & 108a *trimmed heart* ``(U+2665):`` |heart|), and _`inline hyperlink targets` 109(see Targets_ below for a reference back to here). Character-level 110inline markup is also possible (although exceedingly ugly!) in *re*\ 111``Structured``\ *Text*. Problems are indicated by |problematic| text 112(generated by processing errors; this one is intentional). Here is a 113reference to the doctitle_ and the subtitle_. 114 115__ http://www.python.org/ 116__ https://docutils.sourceforge.io/ 117 118The default role for interpreted text is `Title Reference`. Here are 119some explicit interpreted text roles: a PEP reference (:PEP:`287`); an 120RFC reference (:RFC:`2822`); an abbreviation (:ab:`abb.`), an acronym 121(:ac:`reST`), code (:code:`print "hello world"`); a :sub:`subscript`; 122a :sup:`superscript` and explicit roles for :title:`Docutils`' 123:emphasis:`standard` :strong:`inline` :literal:`markup`. 124 125.. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! 126 127Let's test wrapping and whitespace significance in inline literals: 128``This is an example of --inline-literal --text, --including some-- 129strangely--hyphenated-words. Adjust-the-width-of-your-browser-window 130to see how the text is wrapped. -- ---- -------- Now note the 131spacing between the words of this sentence (words 132should be grouped in pairs).`` 133 134If the ``--pep-references`` option was supplied, there should be a 135live link to PEP 258 here. 136 137Bullet Lists 138------------ 139 140- A bullet list 141 142 + Nested bullet list. 143 + Nested item 2. 144 145- Item 2. 146 147 Paragraph 2 of item 2. 148 149 * Nested bullet list. 150 * Nested item 2. 151 152 - Third level. 153 - Item 2. 154 155 * Nested item 3. 156 157 * This nested list should be compacted by the HTML writer. 158 159 .. _target: 160 161 .. Even if this item contains a target and a comment. 162 163Enumerated Lists 164---------------- 165 1661. Arabic numerals. 167 168 a) lower alpha) 169 170 (i) (lower roman) 171 172 A. upper alpha. 173 174 I) upper roman) 175 1762. Lists that don't start at 1: 177 178 3. Three 179 180 4. Four 181 182 C. C 183 184 D. D 185 186 iii. iii 187 188 iv. iv 189 190Definition Lists 191---------------- 192 193Term 194 Definition 195Term : classifier 196 Definition paragraph 1. 197 198 Definition paragraph 2. 199Term 200 Definition 201Term : classifier one : classifier two 202 Definition 203 204Field Lists 205----------- 206 207:what: Field lists map field names to field bodies, like database 208 records. They are often part of an extension syntax. They are 209 an unambiguous variant of RFC 2822 fields. 210 211:how arg1 arg2: 212 213 The field marker is a colon, the field name, and a colon. 214 215 The field body may contain one or more body elements, indented 216 relative to the field marker. 217 218:credits: 219 220 .. class:: credits 221 222 This paragraph has the `credits` class set. (This is actually not 223 about credits but just for ensuring that the class attribute 224 doesn't get stripped away.) 225 226Option Lists 227------------ 228 229For listing command-line options: 230 231-a command-line option "a" 232-b file options can have arguments 233 and long descriptions 234--long options can be long also 235--input=file long options can also have 236 arguments 237 238--very-long-option 239 The description can also start on the next line. 240 241 The description may contain multiple body elements, 242 regardless of where it starts. 243 244-x, -y, -z Multiple options are an "option group". 245-v, --verbose Commonly-seen: short & long options. 246-1 file, --one=file, --two file 247 Multiple options with arguments. 248/V DOS/VMS-style options too 249 250There must be at least two spaces between the option and the 251description. 252 253Literal Blocks 254-------------- 255 256Literal blocks are indicated with a double-colon ("::") at the end of 257the preceding paragraph (over there ``-->``). They can be indented:: 258 259 if literal_block: 260 text = 'is left as-is' 261 spaces_and_linebreaks = 'are preserved' 262 markup_processing = None 263 264Or they can be quoted without indentation:: 265 266>> Great idea! 267> 268> Why didn't I think of that? 269 270Line Blocks 271----------- 272 273This section tests line blocks. Line blocks are body elements which 274consist of lines and other line blocks. Nested line blocks cause 275indentation. 276 277| This is a line block. It ends with a blank line. 278| New lines begin with a vertical bar ("|"). 279| Line breaks and initial indent are significant, and preserved. 280| Continuation lines are also possible. A long line that is intended 281 to wrap should begin with a space in place of the vertical bar. 282| The left edge of a continuation line need not be aligned with 283 the left edge of the text above it. 284 285| This is a second line block. 286| 287| Blank lines are permitted internally, but they must begin with a "|". 288 289Another line block, surrounded by paragraphs: 290 291| And it's no good waiting by the window 292| It's no good waiting for the sun 293| Please believe me, the things you dream of 294| They don't fall in the lap of no-one 295 296Take it away, Eric the Orchestra Leader! 297 298 | A one, two, a one two three four 299 | 300 | Half a bee, philosophically, 301 | must, *ipso facto*, half not be. 302 | But half the bee has got to be, 303 | *vis a vis* its entity. D'you see? 304 | 305 | But can a bee be said to be 306 | or not to be an entire bee, 307 | when half the bee is not a bee, 308 | due to some ancient injury? 309 | 310 | Singing... 311 312A line block, like the following poem by Christian Morgenstern, can 313also be centre-aligned: 314 315.. class:: language-de align-center 316 317| **Die Trichter** 318| 319| Zwei Trichter wandeln durch die Nacht. 320| Durch ihres Rumpfs verengten Schacht 321| fließt weißes Mondlicht 322| still und heiter 323| auf ihren 324| Waldweg 325| u. s. 326| w. 327| 328 329Block Quotes 330------------ 331 332Block quotes consist of indented body elements: 333 334 My theory by A. Elk. Brackets Miss, brackets. This theory goes 335 as follows and begins now. All brontosauruses are thin at one 336 end, much much thicker in the middle and then thin again at the 337 far end. That is my theory, it is mine, and belongs to me and I 338 own it, and what it is too. 339 340 -- Anne Elk (Miss) 341 342The language of a quote (like any other object) can be specified by 343a class attribute: 344 345.. class:: language-fr 346 347.. 348 349 ReStructuredText est un langage de balisage léger utilisé 350 notamment dans la documentation du langage Python. 351 352Doctest Blocks 353-------------- 354 355>>> print 'Python-specific usage examples; begun with ">>>"' 356Python-specific usage examples; begun with ">>>" 357>>> print '(cut and pasted from interactive Python sessions)' 358(cut and pasted from interactive Python sessions) 359 360Footnotes 361--------- 362 363.. [1] A footnote contains body elements, consistently indented by at 364 least 3 spaces. 365 366 This is the footnote's second paragraph. 367 368.. [#label] Footnotes may be numbered, either manually (as in [1]_) or 369 automatically using a "#"-prefixed label. This footnote has a 370 label so it can be referred to from multiple places, both as a 371 footnote reference ([#label]_) and as a `hyperlink reference`__. 372 373 __ label_ 374 375.. [#] This footnote is numbered automatically and anonymously using a 376 label of "#" only. 377 378 This is the second paragraph. 379 380 And this is the third paragraph. 381 382.. [*] Footnotes may also use symbols, specified with a "*" label. 383 Here's a reference to the next footnote: [*]_. 384 385.. [*] This footnote shows the next symbol in the sequence. 386 387.. [4] Here's an unreferenced footnote, with a reference to a 388 nonexistent footnote: [5]_. 389 390Citations 391--------- 392 393.. [CIT2002] Citations are text-labeled footnotes. They may be 394 rendered separately and differently from footnotes. 395 396Here's a reference to the above, [CIT2002]_, and a [nonexistent]_ 397citation. 398 399.. _Another Target: 400 401Targets 402------- 403 404.. _example: 405 406This paragraph is pointed to by the explicit "example" target. A 407reference can be found under `Inline Markup`_, above. `Inline 408hyperlink targets`_ are also possible. 409 410Section headers are implicit targets, referred to by name. See 411Targets_, which is a subsection of `Body Elements`_. 412 413Explicit external targets are interpolated into references such as 414"Python_". 415 416.. _Python: http://www.python.org/ 417 418Targets may be indirect and anonymous. Thus `this phrase`__ may also 419refer to the Targets_ section. 420 421__ Targets_ 422 423Here's a `hyperlink reference without a target`_, which generates an 424error. 425 426Duplicate Target Names 427`````````````````````` 428 429Duplicate names in section headers or other implicit targets will 430generate "info" (level-1) system messages. Duplicate names in 431explicit targets will generate "warning" (level-2) system messages. 432 433Duplicate Target Names 434`````````````````````` 435 436Since there are two "Duplicate Target Names" section headers, we 437cannot uniquely refer to either of them by name. If we try to (like 438this: `Duplicate Target Names`_), an error is generated. 439 440Directives 441---------- 442 443.. contents:: :local: 444 445These are just a sample of the many reStructuredText Directives. For 446others, please see `reStructuredText Directives`__. 447 448__ https://docutils.sourceforge.io/docs/ref/rst/directives.html 449 450Document Parts 451`````````````` 452 453An example of the "contents" directive can be seen above this section 454(a local, untitled table of contents_) and at the beginning of the 455document (a document-wide `table of contents`_). 456 457Images and Figures 458`````````````````` 459 460An image directive (also clickable -- a hyperlink reference): 461 462.. image:: ../../../docs/user/rst/images/title.png 463 :class: class1 class2 464 :target: directives_ 465 :width: 70% 466 467Image with multiple IDs: 468 469.. _image target 1: 470.. _image target 2: 471.. _image target 3: 472.. image:: ../../../docs/user/rst/images/biohazard.png 473 474A centered image: 475 476.. image:: ../../../docs/user/rst/images/biohazard.png 477 :align: center 478 479A left-aligned image: 480 481.. image:: ../../../docs/user/rst/images/biohazard.png 482 :align: left 483 484This paragraph might flow around the image. 485The specific behavior depends upon the style sheet and 486the browser or rendering software used. 487 488A right-aligned image: 489 490.. image:: ../../../docs/user/rst/images/biohazard.png 491 :align: right 492 493This paragraph might flow around the image. 494The specific behavior depends upon the style sheet and 495the browser or rendering software used. 496 497For inline images see `Substitution Definitions`_. 498 499Image size: 500 501An image 2 em wide: 502 503.. image:: ../../../docs/user/rst/images/biohazard.png 504 :width: 2 em 505 506An image 2 cm wide and 15 pixel high: 507 508.. image:: ../../../docs/user/rst/images/biohazard.png 509 :width: 2cm 510 :height: 15 px 511 512Relative units allow adaption of the image to the screen or paper size. 513An image occupying 50% of the line width: 514 515.. image:: ../../../docs/user/rst/images/title.png 516 :width: 50% 517 518A *figure* is an image with a caption and/or a legend. With page-based output 519media, figures might float to a different position if this helps the page 520layout. 521 522.. figure:: ../../../docs/user/rst/images/title.png 523 :figclass: figclass1 figclass2 524 :class: class1 class2 525 :alt: reStructuredText, the markup syntax 526 :width: 258 527 528 Plaintext markup syntax and parser system. 529 530 +------------+-----------------------------------------------+ 531 | re | Revised, revisited, based on 're' module. | 532 +------------+-----------------------------------------------+ 533 | Structured | Structure-enhanced text, structuredtext. | 534 +------------+-----------------------------------------------+ 535 | Text | Well it is, isn't it? | 536 +------------+-----------------------------------------------+ 537 538 This paragraph is also part of the legend. 539 540A left-aligned figure, 70% wide: 541 542.. figure:: ../../../docs/user/rst/images/biohazard.png 543 :figclass: figclass1 figclass2 544 :class: class1 class2 545 :alt: reStructuredText, the markup syntax 546 :align: left 547 :width: 40 px 548 :figwidth: 70 % 549 550 This is the caption. 551 552 This is the legend. 553 554 The legend may consist of several paragraphs. 555 556This paragraph might flow around the figure. 557 558The specific behavior depends upon the style sheet and the browser or 559rendering software used. 560 561A centered figure: 562 563.. figure:: ../../../docs/user/rst/images/biohazard.png 564 :align: center 565 :width: 40 px 566 567 This is the caption. 568 569 This is the legend. 570 571 The legend may consist of several paragraphs. 572 573This paragraph might flow around the figure. 574 575The specific behavior depends upon the style sheet and the browser or 576rendering software used. 577 578A right-aligned figure: 579 580.. figure:: ../../../docs/user/rst/images/biohazard.png 581 :align: right 582 :width: 40 px 583 584 This is the caption. 585 586 This is the legend. 587 588 The legend may consist of several paragraphs. 589 590This paragraph might flow around the figure. The specific behavior depends 591upon the style sheet and the browser or rendering software used. 592 593 594Tables 595`````` 596 597Tables may be given titles and additional arguments with the *table* 598directive: 599 600.. Table:: left-aligned table 601 :align: left 602 603 ===== ===== 604 A not A 605 ===== ===== 606 False True 607 True False 608 ===== ===== 609 610.. Table:: center-aligned table 611 :align: center 612 613 ===== ===== 614 A not A 615 ===== ===== 616 False True 617 True False 618 ===== ===== 619 620.. Table:: right-aligned table 621 :align: right 622 623 ===== ===== 624 A not A 625 ===== ===== 626 False True 627 True False 628 ===== ===== 629 630With the "widths" argument "auto" (or "class" value "colwidths-auto"), 631column widths are determined by the backend (if supported by the 632writer/backend). 633 634.. _target1: 635.. _target2: 636 637.. table:: 638 :widths: auto 639 640 ======= ======= ========== 641 A B A or B 642 ======= ======= ========== 643 False False False 644 True False True 645 False True True 646 True True True 647 ======= ======= ========== 648 649 650Admonitions 651``````````` 652 653.. Attention:: Directives at large. 654 655.. Caution:: 656 657 Don't take any wooden nickels. 658 659.. DANGER:: Mad scientist at work! 660 661.. Error:: Does not compute. 662 663.. Hint:: It's bigger than a bread box. 664 665.. Important:: 666 - Wash behind your ears. 667 - Clean up your room. 668 - Call your mother. 669 - Back up your data. 670 671.. Note:: This is a note. 672 673.. Tip:: 15% if the service is good. 674 675.. WARNING:: Strong prose may provoke extreme mental exertion. 676 Reader discretion is strongly advised. 677 678.. admonition:: And, by the way... 679 680 You can make up your own admonition too. 681 682 .. _Docutils: https://docutils.sourceforge.io/ 683 684Topics, Sidebars, and Rubrics 685````````````````````````````` 686 687*Sidebars* are like miniature, parallel documents. 688 689.. sidebar:: Optional Sidebar Title 690 :subtitle: Optional Subtitle 691 692 This is a sidebar. It is for text outside the flow of the main 693 text. 694 695 .. rubric:: This is a rubric inside a sidebar 696 697 Sidebars often appear beside the main text with a border and a different 698 background or font color. 699 700A *topic* is like a block quote with a title, or a self-contained section 701with no subsections. 702 703.. topic:: Topic Title 704 705 This is a topic. 706 707A *rubric* is like an informal heading that doesn't correspond to the 708document's structure. It is typically highlighted in red (hence the name). 709 710.. rubric:: This is a rubric 711 712Topics and rubrics can be used at places where a `section title`_ is not 713allowed (e.g. inside a directive). 714 715Target Footnotes 716```````````````` 717 718.. target-notes:: 719 720 721Replacement Text 722```````````````` 723 724I recommend you try |Python|_. 725 726.. |Python| replace:: Python, *the* best language around 727 728Compound Paragraph 729`````````````````` 730 731The *compound* directive is used to create a "compound paragraph", which 732is a single logical paragraph containing multiple physical body 733elements. For example: 734 735.. compound:: 736 737 The 'rm' command is very dangerous. If you are logged 738 in as root and enter :: 739 740 cd / 741 rm -rf * 742 743 you will erase the entire contents of your file system. 744 745Test the handling and display of compound paragraphs: 746 747.. compound:: 748 :class: some-class 749 750 Compound 2, paragraph 1, 751 752 compound 2, paragraph 2, 753 754 * list item 1, 755 * list item 2, 756 757 compound 2, paragraph 3. 758 759.. compound:: 760 761 Compound 3, only consisting of one paragraph. 762 763.. compound:: 764 765 :: 766 767 Compound 4. 768 This one starts with a literal block. 769 770 Compound 4, paragraph following the literal block. 771 772Now something *really* perverted -- a nested compound block. This is 773just to test that it works at all; the results don't have to be 774meaningful. 775 776.. compound:: 777 778 Compound 5, block 1 (a paragraph). 779 780 .. compound:: 781 782 Compound 6 is block 2 in compound 5. 783 784 Compound 6, another paragraph. 785 786 Compound 5, block 3 (a paragraph). 787 788.. compound:: 789 790 Compound 7, tests the inclusion of various block-level 791 elements in one logical paragraph. First a table, 792 793 +--------------------+--------------------+--------------------+ 794 | Left cell, first | Middle cell, | Right cell. | 795 | paragraph. | consisting of | | 796 | | exactly one | Paragraph 2. | 797 | Left cell, second | paragraph. | | 798 | paragraph. | | Paragraph 3. | 799 +--------------------+--------------------+--------------------+ 800 801 followed by a paragraph. This physical paragraph is 802 actually a continuation of the paragraph before the table. It is followed 803 by 804 805 a quote and 806 807 #. an enumerated list, 808 809 a paragraph, 810 811 --an option list, 812 813 a paragraph, 814 815 :a field: list, 816 817 a paragraph, 818 819 a definition 820 list, 821 822 a paragraph, an image: 823 824 .. image:: ../../../docs/user/rst/images/biohazard.png 825 826 a paragraph, 827 828 | a line 829 | block, 830 831 a paragraph followed by a comment, 832 833 .. this is a comment 834 835 a paragraph, a 836 837 .. note:: with content 838 839 and the final paragraph of the compound 7. 840 841Parsed Literal Blocks 842````````````````````` 843 844.. parsed-literal:: 845 846 This is a parsed literal block. 847 This line is indented. The next line is blank. 848 849 Inline markup is supported, e.g. *emphasis*, **strong**, ``literal 850 text``, :sub:`sub-` and :sup:`super`\ scripts, 851 inline formulas: :math:`A = 2 \pi r^2`, 852 footnotes [1]_, _`hyperlink targets`, and `references 853 <http://www.python.org/>`_. 854 855Code 856```` 857 858Blocks of source code can be set with the `code` directive. If the code 859language is specified, the content is parsed and tagged by the Pygments_ 860syntax highlighter and can be formatted with a style sheet. (Code parsing 861is turned off using the ``syntax-highlight`` config setting in the test 862conversions in order to get identical results with/without installed 863Pygments highlighter.) 864 865.. code:: python 866 867 print 'This is Python code.' 868 869The ``:number-lines:`` option (with optional start value) generates line 870numbers: 871 872.. code:: python 873 :number-lines: 8 874 875 # print integers from 0 to 9: 876 for i in range(10): 877 print i 878 879For inline code snippets, there is the `code` role, which can be used 880directly (the code will not be parsed/tagged, as the language is not known) 881or as base for special code roles, e.g. the LaTeX code in the next 882paragraph. 883 884.. role:: tex(code) 885 :language: tex 886 887Docutils uses LaTeX syntax for math directives and roles: 888:tex:`\alpha = f(x)` prints :math:`\alpha = f(x)`. 889 890The ``:code:`` option of the `include` directive sets the included content 891as a code block, here the rst file ``header_footer.txt`` with line numbers: 892 893.. include:: header_footer.txt 894 :code: rst 895 :number-lines: 896 897.. _Pygments: http://pygments.org/ 898 899 900Meta 901```` 902 903The `“meta” directive`__ is used to specify metadata to be stored in, 904e.g., HTML META tags or ODT file properties. 905 906.. meta:: 907 :keywords: reStructuredText, test, parser 908 :description lang=en: A test document, containing at least one 909 example of each reStructuredText construct. 910 911__ https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata 912 913 914Substitution Definitions 915------------------------ 916 917An inline image (|example|) example: 918 919.. |EXAMPLE| image:: ../../../docs/user/rst/images/biohazard.png 920 921A Unicode example: 922 923.. |heart| unicode:: 0x2665 924 :trim: 925 926(Substitution definitions are not visible in the HTML source.) 927 928Comments 929-------- 930 931Here's one: 932 933.. Comments begin with two dots and a space. Anything may 934 follow, except for the syntax of footnotes, hyperlink 935 targets, directives, or substitution definitions. 936 937 Double-dashes -- "--" -- must be escaped somehow in HTML output. 938 939 Comments may contain non-ASCII characters: ä ö ü æ ø å 940 941(View the HTML source to see the comment.) 942 943Raw text 944-------- 945 946This does not necessarily look nice, because there may be missing white space. 947 948It's just there to freeze the behavior. 949 950.. raw:: html latex 951 952 A test. 953 954.. raw:: html latex 955 956 Second test. 957 958.. class:: myclass 959 960.. raw:: html latex 961 962 Another test with myclass set. 963 964.. role:: raw-role(raw) 965 :format: html latex 966 :class: myrawroleclass 967 968This is the :raw-role:`fourth test` with myrawroleclass set. 969 970.. raw:: html 971 972 Fifth test in HTML.<br />Line two. 973 974.. raw:: latex 975 976 Fifth test in LaTeX.\\Line two. 977 978Container 979--------- 980 981.. container:: custom 982 983 paragraph 1 984 985 paragraph 2 986
