/ directives.rst
directives.rst
1 .. include:: header.rst 2 3 ============================= 4 reStructuredText Directives 5 ============================= 6 :Author: David Goodger 7 :Contact: docutils-develop@lists.sourceforge.net 8 :Revision: $Revision: 10190 $ 9 :Date: $Date: 2025-07-30 10:22:32 +0200 (Mi, 30. Jul 2025) $ 10 :Copyright: This document has been placed in the public domain. 11 12 .. contents:: 13 :depth: 2 14 15 This document describes the directives implemented in the reference 16 reStructuredText parser. 17 18 Directives have the following syntax:: 19 20 +-------+-------------------------------+ 21 | ".. " | directive type "::" directive | 22 +-------+ block | 23 | | 24 +-------------------------------+ 25 26 Directives begin with an explicit markup start (two periods and a 27 space), followed by the directive type and two colons (collectively, 28 the "directive marker"). The directive block begins immediately after 29 the directive marker, and includes all subsequent indented lines. The 30 directive block is divided into arguments, options (a field list), and 31 content (in that order), any of which may appear. See the Directives_ 32 section in the `reStructuredText Markup Specification`_ for syntax 33 details. 34 35 Descriptions below list "doctree elements" (document tree element 36 names; XML DTD generic identifiers) corresponding to individual directives. 37 For details on the hierarchy of elements, please see `The Docutils 38 Document Tree`_ and the `Docutils Generic DTD`_ XML document type definition. 39 For directive implementation details, see `Creating reStructuredText 40 Directives`_ and the `source <../../../docutils/parsers/rst/directives>`__. 41 42 .. _Docutils Generic DTD: ../docutils.dtd 43 .. _Creating reStructuredText Directives: 44 ../../howto/rst-directives.html 45 46 47 ------------- 48 Admonitions 49 ------------- 50 51 Admonitions ("safety messages" or "hazard statements") can appear anywhere 52 an ordinary body element can. They contain arbitrary body elements. 53 Typically, an admonition is rendered as an offset block in a document, 54 sometimes outlined or shaded. 55 56 Docutils defines a `generic admonition`_ as well as a set of 57 `specific admonitions`_. 58 59 60 .. _attention: 61 .. _caution: 62 .. _danger: 63 .. _error: 64 .. _hint: 65 .. _important: 66 .. _note: 67 .. _tip: 68 .. _warning: 69 70 Specific Admonitions 71 ==================== 72 73 .. class:: field-indent-13em 74 75 :Directive Types: "attention", "caution", "danger", "error", "hint", 76 "important", "note", "tip", "warning" 77 :Doctree Elements: `\<attention>`_, `\<caution>`_, `\<danger>`_, 78 `\<error>`_, `\<hint>`_, `\<important>`_, 79 `\<note>`_, `\<tip>`_, `\<warning>`_ 80 :Directive Arguments: none 81 :Directive Options: `class <class option_>`_, name_ 82 :Directive Content: Interpreted as body elements. 83 84 Specific admonitions are rendered with a title matching the admonition type. 85 For example:: 86 87 .. DANGER:: 88 Beware killer rabbits! 89 90 This directive might be rendered something like this:: 91 92 +------------------------+ 93 | !DANGER! | 94 | | 95 | Beware killer rabbits! | 96 +------------------------+ 97 98 Any text immediately following the directive indicator (on the same 99 line and/or indented on following lines) is interpreted as a directive 100 block and is parsed for normal body elements. For example, the 101 following "note" admonition directive contains one paragraph and a 102 bullet list consisting of two list items:: 103 104 .. note:: This is a note admonition. 105 This is the second line of the first paragraph. 106 107 - The note contains all indented body elements 108 following. 109 - It includes this bullet list. 110 111 112 .. _admonition: 113 114 Generic Admonition 115 ================== 116 117 .. class:: field-indent-13em 118 119 :Directive Type: "admonition" 120 :Doctree Elements: `\<admonition>`_, `\<title>`_ 121 :Directive Arguments: one, required (admonition title) 122 :Directive Options: `class <class option_>`_, name_ 123 :Directive Content: Interpreted as body elements. 124 125 This is a generic, titled admonition. The title may be anything the 126 author desires. 127 128 The author-supplied title is also used as a `classes attribute`_ value 129 after `identifier normalization`_ and adding the prefix "admonition-". 130 For example, this admonition:: 131 132 .. admonition:: And, by the way... 133 134 You can make up your own admonition too. 135 136 becomes the following document tree (pseudo-XML):: 137 138 <document source="test data"> 139 <admonition classes="admonition-and-by-the-way"> 140 <title> 141 And, by the way... 142 <paragraph> 143 You can make up your own admonition too. 144 145 The `class <class option_>`_ option overrides the generated 146 `classes attribute`_ value. 147 148 149 -------- 150 Images 151 -------- 152 153 There are two directives to include images: image_ and figure_. 154 The table below provides a non exhaustive overview of 155 supported image formats. 156 157 .. attention:: 158 159 It is up to the author to ensure compatibility of the image data format 160 with the output format or user agent (LaTeX engine, `HTML browser`__, …). 161 162 .. _image formats: 163 164 =========== ====== ====== ===== ===== ===== ===== ===== ===== ===== ===== 165 .. SVG PDF PNG JPG GIF APNG AVIF WebM MP4 OGG 166 =========== ====== ====== ===== ===== ===== ===== ===== ===== ===== ===== 167 .. vector raster video [#video]_ 168 ----------- ------------- ----------------------------- ----------------- 169 HTML4_ [#]_ ✓ ✓ ✓ ✓ (✓) (✓) (✓) (✓) (✓) 170 171 HTML5_ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ 172 173 LaTeX_ [#]_ ✓ [#]_ ✓ ✓ ✓ 174 175 manpage_ 176 177 ODT_ ✓ ✓ ✓ ✓ ✓ 178 =========== ====== ====== ===== ===== ===== ===== ===== ===== ===== ===== 179 180 .. [#video] 181 The `html5 writer`_ uses the ``<video>`` tag if the image URI 182 ends with an extension matching one of the listed video formats 183 (since Docutils 0.17). 184 185 .. [#] The html4 writer uses an ``<object>`` tag for SVG images and 186 videos for compatibility with older browsers and for XHTML1.1 187 conformance respectively. 188 189 .. [#] When compiling with ``pdflatex``, ``xelatex``, or ``lualatex``. 190 The original ``latex`` engine supports only the EPS image format. 191 Some build systems, e.g. rubber_ support additional formats 192 via on-the-fly image conversion. For details, see section 193 `image inclusion`__ in the LaTeX writer documentation. 194 195 .. [#] New in Docutils 0.22. 196 The `"svg" package`_ must be listed in the stylesheet__ setting. 197 198 __ https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types 199 .. _HTML4: 200 .. _html4 writer: ../../user/html.html#html4css1 201 .. _HTML5: 202 .. _html5 writer: ../../user/html.html#html5 203 .. _LaTeX: 204 .. _LaTeX writer: ../../user/latex.html 205 .. _ODT: ../../user/odt.html 206 .. _manpage: ../../user/manpage.html 207 .. _rubber: https://gitlab.com/latex-rubber/rubber 208 __ ../../user/latex.html#image-inclusion 209 .. _"svg" package: https://ctan.org/pkg/svg 210 __ ../../user/config.html#stylesheet-latex-writers 211 212 213 Image 214 ===== 215 216 .. class:: field-indent-13em 217 218 :Directive Type: "image" 219 :Doctree Elements: `\<image>`_, `\<reference>`_ (only with option "target_") 220 :Directive Arguments: one, required (image URI_) 221 :Directive Options: `see below <image options_>`__ 222 :Directive Content: none 223 :Configuration Setting: image_loading_ (only `HTML5 writer`_) 224 225 An "image" is a simple picture:: 226 227 .. image:: picture.png 228 229 A `URI reference`_ to the image source file is specified in the directive 230 argument. As with hyperlink targets, the image URI may begin on the 231 same line as the explicit markup start and target name, or it may 232 begin in an indented text block immediately following, with no 233 intervening blank lines. If there are multiple lines in the link 234 block, they are stripped of leading and trailing whitespace and joined 235 together. 236 237 Optionally, the image link block may contain a flat field list, the 238 `image options`_. For example:: 239 240 .. image:: picture.jpeg 241 :height: 100px 242 :width: 200 px 243 :scale: 50 % 244 :loading: embed 245 :alt: alternate text 246 :align: right 247 248 249 *Inline images* can be defined with an "image" directive in a `substitution 250 definition`_, e.g. :: 251 252 |Red light| means stop, |green light| means go. 253 254 .. |red light| image:: red_light.png 255 :align: top 256 .. |green light| image:: green_light.png 257 :align: bottom 258 259 .. _image options: 260 261 The "image" directive recognizes the common options `class <class option_>`_ 262 and name_ as well as 263 264 ``align`` : "top", "middle", "bottom", "left", "center", or "right" 265 The alignment of the image, equivalent to the HTML ``<img>`` tag's 266 deprecated "align" attribute or the corresponding "vertical-align" and 267 "text-align" CSS properties. 268 The values "top", "middle", and "bottom" 269 control an image's vertical alignment (relative to the text 270 baseline); they are only useful for inline images (substitutions). 271 The values "left", "center", and "right" control an image's 272 horizontal alignment, allowing the image to float and have the 273 text flow around it. The specific behaviour depends upon the 274 browser or rendering software used. 275 276 ``alt`` : text_ 277 Alternate text: a short description of the image, displayed by 278 applications that cannot display images, or spoken by applications 279 for visually impaired users. 280 281 ``height`` : length_ 282 The desired height of the image. 283 Used to reserve space or scale the image vertically. When the scale_ 284 option is also specified, they are combined. For example, a height of 285 200px and a scale of 50 is equivalent to a height of 100px with no scale. 286 287 .. _loading: 288 289 ``loading`` : "embed", "link", or "lazy" 290 Set the `loading attribute`_ to indicate the 291 preferred handling by the Docutils Writer. [#]_ 292 293 :embed: Embed the image into the output document. [#]_ 294 :link: Refer to the image via its URI. 295 :lazy: Refer to the image. The HTML5 writer additionally 296 specifies the "`lazy loading attribute`_". 297 298 (New in Docutils 0.21.) 299 300 .. _scale: 301 302 ``scale`` : integer percentage (the "%" symbol is optional) 303 The uniform scaling factor of the image. The default is "100 %", 304 i.e. no scaling. 305 If the output format does not support a scaling attribute (e.g. HTML), 306 the Docutils writer tries to determine missing size specifications from 307 the image file (requires the `Python Imaging Library`_). 308 309 .. _target: 310 311 ``target`` : URI_ or `reference name`_ 312 Nest the image in a hyperlink reference element (make it "clickable"). 313 The option argument may be a URI reference or a reference name 314 with underscore suffix (e.g. ```a name`_``). 315 316 ``width`` : length_ or percentage_ of the current line width 317 The width of the image. 318 Used to reserve space or scale the image horizontally. As with ``height`` 319 above, when the scale_ option is also specified, they are combined. 320 321 .. [#] Currently only recognized by the `HTML5 writer`_ 322 (overriding the `image_loading`_ configuration setting). 323 The ODF/ODT writer always embeds images in the 324 ``*.odt`` document, XML and LaTeX writers link to the image. 325 The behaviour may change for the ODT and XML writers but 326 images cannot be embedded in a LaTeX source. 327 328 .. [#] The `HTML5 writer`_, embeds SVG images directly and other images 329 as base64_ encoded `data URI`_. 330 331 .. _lazy loading attribute: https://html.spec.whatwg.org/multipage/ 332 urls-and-fetching.html#lazy-loading-attributes 333 .. _base64: https://en.wikipedia.org/wiki/Base64 334 .. _data URI: https://en.wikipedia.org/wiki/Data_URI_scheme 335 336 337 Figure 338 ====== 339 340 .. class:: field-indent-13em 341 342 :Directive Type: "figure" 343 :Doctree Elements: `\<figure>`_, `\<image>`_, 344 `\<caption>`_, `\<legend>`_ 345 :Directive Arguments: one, required (image URI_) 346 :Directive Options: `see below <figure options_>`__ 347 :Directive Content: Interpreted as the figure caption and an optional 348 legend. 349 350 A "figure" consists of image_ data (including `image options`_), an optional 351 caption (a single paragraph), and an optional legend (arbitrary body 352 elements). On paged output media, figures may float to a different 353 position if this helps the page layout. 354 :: 355 356 .. figure:: picture.png 357 :scale: 50 % 358 :alt: map to buried treasure 359 360 This is the caption of the figure (a simple paragraph). 361 362 The legend consists of all elements after the caption. In this 363 case, the legend consists of this paragraph and the following 364 table: 365 366 +-----------------------+-----------------------+ 367 | Symbol | Meaning | 368 +=======================+=======================+ 369 | .. image:: tent.png | Campground | 370 +-----------------------+-----------------------+ 371 | .. image:: waves.png | Lake | 372 +-----------------------+-----------------------+ 373 | .. image:: peak.png | Mountain | 374 +-----------------------+-----------------------+ 375 376 There must be blank lines before the caption paragraph and before the 377 legend. To specify a legend without a caption, use an empty comment 378 ("..") in place of the caption. 379 380 .. _figure options: 381 382 The "figure" directive supports the `common options`_ and all 383 `options of the "image" directive <image options_>`__. 384 These options (except ``align``) are passed on to the contained image. 385 386 ``align`` : "left", "center", or "right" 387 The horizontal alignment of the figure. The specific behaviour 388 depends upon the browser or rendering software used. In HTML, the 389 values "left" and "right" allow text to flow around the figure. 390 391 In addition, the following options are recognized: 392 393 ``figclass`` : space separated list of `class names`_ 394 Set a `classes attribute`_ value on the <figure> element 395 (the "class__" option is applied to the nested <image>). 396 397 __ `class option`_ 398 399 ``figname`` : text_ 400 Add *text* to the `names attribute`_ of the <figure> element 401 (the "name_" option is applied to the nested <image>). 402 New in Docutils 0.22. 403 404 ``figwidth`` : "image", length_, or percentage_ of current line width 405 The width of the figure. 406 Limits the horizontal space used by the figure. 407 A special value of "image" is allowed, in which case the 408 included image's actual width is used (requires the `Python Imaging 409 Library`_). If the image file is not found or the required software is 410 unavailable, this option is ignored. 411 412 Sets the `width attribute`_ of the `\<figure>`_ doctree element. 413 414 This option does not scale the included image; use the ``width`` 415 `image option <image options_>`__ for that. :: 416 417 +---------------------------+ 418 | figure | 419 | | 420 |<------ figwidth --------->| 421 | | 422 | +---------------------+ | 423 | | image | | 424 | | | | 425 | |<--- width --------->| | 426 | +---------------------+ | 427 | | 428 |The figure's caption should| 429 |wrap at this width. | 430 +---------------------------+ 431 432 .. _Python Imaging Library: 433 .. _Pillow: https://pypi.org/project/Pillow/ 434 435 436 --------------- 437 Body Elements 438 --------------- 439 440 Topic 441 ===== 442 443 .. class:: field-indent-13em 444 445 :Directive Type: "topic" 446 :Doctree Element: `\<topic>`_ 447 :Directive Arguments: one, required (topic title) 448 :Directive Options: `class <class option_>`_, name_ 449 :Directive Content: Interpreted as the topic body. 450 451 A topic is like a block quote with a title, or a self-contained 452 section with no subsections. Use the "topic" directive to indicate a 453 self-contained idea that is separate from the flow of the document. 454 Topics may occur anywhere a section or transition may occur. Body 455 elements and topics may not contain nested topics. 456 457 The directive's sole argument is interpreted as the topic title; the 458 next line must be blank. All subsequent lines make up the topic body, 459 interpreted as body elements. For example:: 460 461 .. topic:: Topic Title 462 463 Subsequent indented lines comprise 464 the body of the topic, and are 465 interpreted as body elements. 466 467 468 Sidebar 469 ======= 470 471 .. class:: field-indent-13em 472 473 :Directive Type: "sidebar" 474 :Doctree Element: `\<sidebar>`_ 475 :Directive Arguments: one, optional (sidebar title) 476 :Directive Options: `see below <sidebar options_>`__ 477 :Directive Content: Interpreted as the sidebar body. 478 479 Sidebars are like miniature, parallel documents that occur inside 480 other documents, providing related or reference material. A sidebar 481 is typically offset by a border and "floats" to the side of the page; 482 the document's main text may flow around it. Sidebars can also be 483 likened to super-footnotes; their content is outside of the flow of 484 the document's main text. 485 486 Sidebars may occur anywhere a section or transition may occur. Body 487 elements (including sidebars) may not contain nested sidebars. 488 489 The directive's sole argument is interpreted as the sidebar title, 490 which may be followed by a subtitle option (see below); the next line 491 must be blank. All subsequent lines make up the sidebar body, 492 interpreted as body elements. For example:: 493 494 .. sidebar:: Optional Sidebar Title 495 :subtitle: Optional Sidebar Subtitle 496 497 Subsequent indented lines comprise 498 the body of the sidebar, and are 499 interpreted as body elements. 500 501 .. _sidebar options: 502 503 Recognizes the common options `class <class option_>`_ and name_ as well as 504 505 ``subtitle`` : text_ 506 The sidebar's subtitle. 507 508 509 Line Block 510 ========== 511 512 .. admonition:: Deprecated 513 514 The "line-block" directive is deprecated. Use the `line block 515 syntax`_ instead. 516 517 .. _line block syntax: restructuredtext.html#line-blocks 518 519 .. class:: field-indent-13em 520 521 :Directive Type: "line-block" 522 :Doctree Element: `\<line_block>`_ 523 :Directive Arguments: none 524 :Directive Options: `class <class option_>`_, name_ 525 :Directive Content: Becomes the body of the line block. 526 527 The "line-block" directive constructs an element where line breaks and 528 initial indentation is significant and inline markup is supported. It 529 is equivalent to a `parsed literal block`_ with different rendering: 530 typically in an ordinary serif typeface instead of a 531 typewriter/monospaced face, and not automatically indented. (Have the 532 line-block directive begin a block quote to get an indented line 533 block.) Line blocks are useful for address blocks and verse (poetry, 534 song lyrics), where the structure of lines is significant. For 535 example, here's a classic:: 536 537 "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by 538 Ewan McTeagle (for Lassie O'Shea): 539 540 .. line-block:: 541 542 Lend us a couple of bob till Thursday. 543 I'm absolutely skint. 544 But I'm expecting a postal order and I can pay you back 545 as soon as it comes. 546 Love, Ewan. 547 548 549 .. _parsed-literal: 550 551 Parsed Literal Block 552 ==================== 553 554 .. class:: field-indent-13em 555 556 :Directive Type: "parsed-literal" 557 :Doctree Element: `\<literal_block>`_ 558 :Directive Arguments: none 559 :Directive Options: `class <class option_>`_, name_ 560 :Directive Content: Becomes the body of the literal block. 561 562 Unlike an ordinary literal block, the "parsed-literal" directive 563 constructs a literal block where the text is parsed for inline markup. 564 It is equivalent to a `line block`_ with different rendering: 565 typically in a typewriter/monospaced typeface, like an ordinary 566 literal block. Parsed literal blocks are useful for adding hyperlinks 567 to code examples. 568 569 However, care must be taken with the text, because inline markup is 570 recognized and there is no protection from parsing. Backslash-escapes 571 may be necessary to prevent unintended parsing. And because the 572 markup characters are removed by the parser, care must also be taken 573 with vertical alignment. Parsed "ASCII art" is tricky, and extra 574 whitespace may be necessary. 575 576 For example, all the element names in this content model are links:: 577 578 .. parsed-literal:: 579 580 ( (title_, subtitle_?)?, 581 decoration_?, 582 (docinfo_, transition_?)?, 583 `%structure.model;`_ ) 584 585 586 Code 587 ==== 588 589 .. class:: field-indent-13em 590 591 :Directive Type: "code" 592 :Doctree Elements: `\<literal_block>`_, `inline elements`_ 593 :Directive Arguments: one, optional (formal language) 594 :Directive Options: `see below <code options_>`__ 595 :Directive Content: Becomes the body of the literal block. 596 :Configuration Setting: syntax_highlight_ 597 598 The "code" directive constructs a literal block. If the code language is 599 specified, the content is parsed by the Pygments_ syntax highlighter and 600 tokens are stored in nested `inline elements`_ with class arguments 601 according to their syntactic category. The actual highlighting requires 602 a custom style-sheet, see the `sandbox/stylesheets`_ for examples. 603 604 For example, the content of the following directive :: 605 606 .. code:: python 607 :number-lines: 608 609 def my_function(): 610 "just a test" 611 print(8/2) 612 613 is parsed and marked up as Python source code. 614 615 The parsing can be turned off with the syntax_highlight_ configuration 616 setting and command line option or by specifying the language as 617 `class <class option_>`_ option instead of directive argument. 618 This also avoids warnings when Pygments_ is not installed or the language 619 is not in the `supported languages and markup formats`_. 620 621 For code in external files, use the "include_" directive with the 622 ``code`` option. For inline code, use the `"code" role`_. 623 624 .. _code options: 625 626 Recognizes the common options `class <class option_>`_ and name_ as well as 627 628 ``number-lines`` : integer_ (start line number, optional) 629 Precede every line with a line number. 630 The optional argument is the number of the first line (default 1). 631 632 .. _sandbox/stylesheets: https://docutils.sourceforge.io/sandbox/stylesheets/ 633 .. _Pygments: https://pygments.org/ 634 .. _supported languages and markup formats: https://pygments.org/languages/ 635 636 637 Math 638 ==== 639 640 .. class:: field-indent-13em 641 642 :Directive Type: "math" 643 :Doctree Element: `\<math_block>`_ 644 :Directive Arguments: none 645 :Directive Options: `class <class option_>`_, name_ 646 :Directive Content: Becomes the body of the math block. 647 (Content blocks separated by a blank line are put in 648 adjacent math blocks.) 649 :Configuration Setting: math_output_ 650 651 The "math" directive inserts blocks with mathematical content 652 (display formulas, equations) into the document. The input format is 653 `LaTeX math syntax`_ with support for Unicode symbols, for example:: 654 655 .. math:: 656 657 α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ) 658 659 Support is limited to a subset of *LaTeX math* by the conversion 660 required for many output formats. For HTML, the `math_output`_ 661 configuration setting (or the corresponding ``--math-output`` 662 command line option) select between alternative output formats with 663 different subsets of supported elements. If a writer does not 664 support math typesetting, the content is inserted verbatim. 665 666 For inline formulas, use the `"math" role`_. 667 668 .. _LaTeX math syntax: ../../ref/rst/mathematics.html 669 670 671 Rubric 672 ====== 673 674 .. class:: field-indent-13em 675 676 :Directive Type: "rubric" 677 :Doctree Element: `\<rubric>`_ 678 :Directive Arguments: one, required (rubric text) 679 :Directive Options: `class <class option_>`_, name_ 680 :Directive Content: none 681 682 .. 683 684 rubric n. 1. a title, heading, or the like, in a manuscript, 685 book, statute, etc., written or printed in red or otherwise 686 distinguished from the rest of the text. ... 687 688 -- Random House Webster's College Dictionary, 1991 689 690 The "rubric" directive inserts a "rubric" element into the document 691 tree. A rubric is like an informal heading that doesn't correspond to 692 the document's structure. 693 694 695 Epigraph 696 ======== 697 698 .. class:: field-indent-13em 699 700 :Directive Type: "epigraph" 701 :Doctree Element: `\<block_quote>`_ 702 :Directive Arguments: none 703 :Directive Options: none 704 :Directive Content: Interpreted as the body of the block quote. 705 706 An epigraph is an apposite (suitable, apt, or pertinent) short 707 inscription, often a quotation or poem, at the beginning of a document 708 or section. 709 710 The "epigraph" directive produces an "epigraph"-class block quote. 711 For example, this input:: 712 713 .. epigraph:: 714 715 No matter where you go, there you are. 716 717 -- Buckaroo Banzai 718 719 becomes this document tree fragment:: 720 721 <block_quote classes="epigraph"> 722 <paragraph> 723 No matter where you go, there you are. 724 <attribution> 725 Buckaroo Banzai 726 727 728 Highlights 729 ========== 730 731 .. class:: field-indent-13em 732 733 :Directive Type: "highlights" 734 :Doctree Element: `\<block_quote>`_ 735 :Directive Arguments: none 736 :Directive Options: none 737 :Directive Content: Interpreted as the body of the block quote. 738 739 Highlights summarize the main points of a document or section, often 740 consisting of a list. 741 742 The "highlights" directive produces a "highlights"-class block quote. 743 See Epigraph_ above for an analogous example. 744 745 746 Pull-Quote 747 ========== 748 749 .. class:: field-indent-13em 750 751 :Directive Type: "pull-quote" 752 :Doctree Element: `\<block_quote>`_ 753 :Directive Arguments: none 754 :Directive Options: none 755 :Directive Content: Interpreted as the body of the block quote. 756 757 A pull-quote is a small selection of text "pulled out and quoted", 758 typically in a larger typeface. Pull-quotes are used to attract 759 attention, especially in long articles. 760 761 The "pull-quote" directive produces a "pull-quote"-class block quote. 762 See Epigraph_ above for an analogous example. 763 764 765 .. compound: 766 767 Compound Paragraph 768 ================== 769 770 .. class:: field-indent-13em 771 772 :Directive Type: "compound" 773 :Doctree Element: `\<compound>`_ 774 :Directive Arguments: none 775 :Directive Options: `class <class option_>`_, name_ 776 :Directive Content: Interpreted as body elements. 777 778 The "compound" directive is used to create a compound paragraph, which 779 is a single logical paragraph containing multiple physical body 780 elements such as simple paragraphs, literal blocks, tables, lists, 781 etc., instead of directly containing text and inline elements. For 782 example:: 783 784 .. compound:: 785 786 The 'rm' command is very dangerous. If you are logged 787 in as root and enter :: 788 789 cd / 790 rm -rf * 791 792 you will erase the entire contents of your file system. 793 794 In the example above, a literal block is "embedded" within a sentence 795 that begins in one physical paragraph and ends in another. 796 797 .. note:: 798 799 The "compound" directive is *not* a generic block-level container 800 like HTML's ``<div>`` element. Do not use it only to group a 801 sequence of elements, or you may get unexpected results. 802 803 If you need a generic block-level container, please use the 804 container_ directive, described below. 805 806 Compound paragraphs are typically rendered as multiple distinct text 807 blocks, with the possibility of variations to emphasize their logical 808 unity: 809 810 * If paragraphs are rendered with a first-line indent, only the first 811 physical paragraph of a compound paragraph should have that indent 812 -- second and further physical paragraphs should omit the indents; 813 * vertical spacing between physical elements may be reduced; 814 * and so on. 815 816 817 Container 818 ========= 819 820 .. class:: field-indent-13em 821 822 :Directive Type: "container" 823 :Doctree Element: `\<container>`_ 824 :Directive Arguments: one or more, optional (`class names`_) 825 :Directive Options: name_ 826 :Directive Content: Interpreted as body elements. 827 828 The "container" directive surrounds its contents (arbitrary body 829 elements) with a generic block-level "container" element. 830 Combined with the optional argument, this is an 831 extension mechanism for users & applications. For example:: 832 833 .. container:: custom 834 835 This paragraph might be rendered in a custom way. 836 837 Parsing the above results in the following pseudo-XML:: 838 839 <container classes="custom"> 840 <paragraph> 841 This paragraph might be rendered in a custom way. 842 843 The "container" directive is the equivalent of HTML's ``<div>`` 844 element. It may be used to group a sequence of elements for user- or 845 application-specific purposes. 846 847 848 -------- 849 Tables 850 -------- 851 852 Formal tables need more structure than the reStructuredText `table syntax`_ 853 supplies. Tables may be given titles with the "table_" directive. 854 Sometimes reStructuredText tables are inconvenient to write, or table 855 data in a standard format is readily available. The "csv-table_" 856 directive supports CSV [#CSV]_ data, the "list-table_" directive uses 857 a list-based input format. 858 859 .. _table syntax: restructuredtext.html#tables 860 861 862 Table 863 ===== 864 865 .. class:: field-indent-13em 866 867 :Directive Type: "table" 868 :Doctree Element: `\<table>`_ 869 :Directive Arguments: one, optional (table caption) 870 :Directive Options: `see below <table options_>`__ 871 :Directive Content: one reStructuredText `grid table`_ or `simple table`_ 872 :Configuration Setting: table_style_ 873 874 The "table" directive is used to provide a table caption 875 or specify options, e.g.:: 876 877 .. table:: Truth table for "not" 878 :widths: auto 879 880 ===== ===== 881 A not A 882 ===== ===== 883 False True 884 True False 885 ===== ===== 886 887 .. _table options: 888 889 Recognizes the common options `class <class option_>`_ and name_ as well as 890 891 ``align`` : "left", "center", or "right" 892 The horizontal alignment of the table (new in Docutils 0.13). 893 894 ``width`` : length_ or percentage_ of the current line width 895 The width of the table. 896 By default, the renderer determines the width of a table 897 from its contents. [#width-from-widths]_ 898 899 ``widths`` : "auto", "grid", or a `list of integers`_ 900 Table column widths. 901 Possible values: 902 903 .. class:: field-indent-7ex run-in 904 905 :"auto": Delegate the determination of column widths to the backend 906 (LaTeX, the HTML browser, ...). 907 908 :"grid": Relative column widths match the widths of the columns 909 in the reStructuredText table markup. 910 911 :list of integers: Specifies relative column widths. 912 Must match the number of table columns. 913 914 The default depends on the writer. 915 The HTML5_ and manpage_ writers default to *"auto"*, 916 the html4_ and LaTeX_ writers default to *"grid"*. [#widths-default]_ 917 918 .. [#width-from-widths] The LaTeX writer determines the `table width 919 from column widths`__ unless the ``widths`` option is set to *"auto"*. 920 921 __ ../../user/latex.html#table-width 922 923 .. [#widths-default] The ``widths`` default of the HTML and LaTeX 924 writers can be configured with the `table_style`_ configuration 925 setting using the special class values "colwidths-auto" or 926 "colwidths-grid". 927 928 929 .. _csv-table: 930 931 CSV Table 932 ========= 933 934 .. class:: field-indent-13em 935 936 :Directive Type: "csv-table" 937 :Doctree Element: `\<table>`_ 938 :Directive Arguments: one, optional (table caption) 939 :Directive Options: `see below <csv-table options_>`__ 940 :Directive Content: A CSV (comma-separated values) table 941 or (with the `file`_ or `url`_ options) none. 942 :Configuration Settings: table_style_, file_insertion_enabled_, root_prefix_ 943 944 .. WARNING:: 945 946 The "csv-table" directive's `file`_ and `url`_ options represent 947 potential security holes. They can be disabled with the 948 "file_insertion_enabled_" runtime setting. 949 950 The "csv-table" directive is used to create a table from CSV 951 (comma-separated values) [#CSV]_ data. The data may be internal 952 (an integral part of the document) or external (a separate file). 953 954 * Block markup and inline markup within cells is supported. 955 Line ends are recognized within quoted cells. 956 957 * There is no support for checking that the number of columns in each 958 row is the same. The directive automatically adds empty entries at 959 the end of short rows. 960 961 .. TODO 962 Add option ``missing-cells`` with keywords "strict", "fill", "span"? 963 (cf. [feature-requests:#103]) 964 965 Example:: 966 967 .. csv-table:: Frozen Delights! 968 :header: "Treat", "Quantity", "Description" 969 :widths: 15, 10, 30 970 971 "Albatross", 2.99, "On a stick!" 972 "Crunchy Frog", 1.49, "If we took the bones out, 973 it wouldn't be crunchy, now would it?" 974 "Gannet Ripple", 1.99, "On a stick!" 975 976 .. _csv-table options: 977 978 Recognizes the common options `class <class option_>`_ and name_ as well as 979 980 ``align`` : "left", "center", or "right" 981 The horizontal alignment of the table. (New in Docutils 0.13) 982 983 .. _delimiter: 984 985 ``delim`` : character_, "tab", or "space" 986 The character used to separate data fields. 987 The special values "tab" and "space" are converted to the respective 988 whitespace characters. [#tab-expansion]_ 989 Defaults to "``,``" (comma). 990 991 ``encoding`` : encoding_ 992 The text encoding of the external CSV data (file or URL). 993 Defaults to the document's `input_encoding`_. 994 995 ``escape`` : character_ 996 A character used to escape the delimiter_ or quote_ characters from 997 the CSV parser. The default is no escape character -- fields may 998 contain delimiter or newline characters if they are quoted, two quote_ 999 characters stand for a literal one, e.g., ``"""Hi!"", he said."``. 1000 1001 .. Caution:: Setting ``escape`` to ``\`` (backslash) interferes with 1002 the reStructuredText `escaping mechanism`_ (applied after CSV 1003 parsing). You will need two backslashes to escape reStructuredText 1004 markup and four backslashes for a literal one. 1005 1006 .. _`file`: 1007 1008 ``file`` : path_ 1009 The local filesystem path to a CSV data file. 1010 1011 ``header`` : text_ (CSV data) 1012 Supplemental data for the table header, added independently of and 1013 before any ``header-rows`` from the main CSV data. Must use the 1014 same CSV format as the main CSV data. [#]_ 1015 1016 ``header-rows`` : integer_ 1017 The number of rows of CSV data to use in the table header. 1018 Defaults to 0. 1019 1020 ``keepspace`` : flag_ 1021 Treat whitespace immediately following the delimiter as 1022 significant. The default is to ignore such whitespace. 1023 1024 .. _quote: 1025 1026 ``quote`` : character_ 1027 The character used to quote fields containing special characters, 1028 such as the delimiter_, quote, or new-line characters. 1029 Defaults to ``"`` (quote). 1030 1031 ``stub-columns`` : integer_ 1032 The number of table columns to use as stubs (row titles, on the left). 1033 Defaults to 0. 1034 1035 .. _`url`: 1036 1037 ``url`` : URI_ 1038 A URI reference to a CSV data file. 1039 1040 ``width`` : length_ or percentage_ of the current line width 1041 The width of the table. 1042 By default, the renderer determines the width of a table 1043 from its contents. [#width-from-widths2]_ 1044 1045 ``widths`` : `list of integers`_ or "auto" 1046 A list of relative column widths. The special value 1047 "auto" delegates the determination of column widths to the backend 1048 (LaTeX, the HTML browser, ...). 1049 1050 The default depends on the writer. 1051 The html5_ and manpage_ writers default to *"auto"*, the html4_ and 1052 LaTeX_ writers default to equal-width columns. [#widths-default]_ 1053 1054 .. [#CSV] CSV (comma separated values) is a common data format generated 1055 by spreadsheet applications and commercial databases. Despite the 1056 "comma" in its name, the field delimiter_ may be any Unicode character. 1057 1058 .. [#tab-expansion] Note, that *tabs* can be used as separator only in 1059 external files because hard tabs in the reStructuredText source are 1060 `converted to spaces`__ before parsing. 1061 1062 __ restructuredtext.html#whitespace 1063 1064 .. [#] Before Docutils 0.21, the header option used a hard-coded 1065 CSV dialect with the backslash as escape character. 1066 1067 .. [#width-from-widths2] The `LaTeX writer defaults to a table width 1068 of 100%`__ unless the ``width`` or ``widths`` option is set. 1069 1070 __ ../../user/latex.html#table-width 1071 1072 1073 .. _list-table: 1074 1075 List Table 1076 ========== 1077 1078 .. class:: field-indent-13em 1079 1080 :Directive Type: "list-table" 1081 :Doctree Element: `\<table>`_ 1082 :Directive Arguments: one, optional (table caption) 1083 :Directive Options: `see below <list-table options_>`__ 1084 :Directive Content: A uniform two-level bullet list. 1085 :Configuration Setting: table_style_ 1086 1087 (This is an initial implementation; `further ideas`__ may be implemented 1088 in the future.) 1089 1090 __ ../../dev/rst/alternatives.html#list-driven-tables 1091 1092 The "list-table" directive is used to create a table from data in a 1093 uniform two-level bullet list. "Uniform" means that each sublist 1094 (second-level list) must contain the same number of list items. 1095 1096 Example:: 1097 1098 .. list-table:: Frozen Delights! 1099 :widths: 15 10 30 1100 :header-rows: 1 1101 1102 * - Treat 1103 - Quantity 1104 - Description 1105 * - Albatross 1106 - 2.99 1107 - On a stick! 1108 * - Crunchy Frog 1109 - 1.49 1110 - If we took the bones out, it wouldn't be 1111 crunchy, now would it? 1112 * - Gannet Ripple 1113 - 1.99 1114 - On a stick! 1115 1116 .. _list-table options: 1117 1118 Recognizes the common options `class <class option_>`_ and name_ as well as 1119 1120 ``align`` : "left", "center", or "right" 1121 The horizontal alignment of the table. 1122 (New in Docutils 0.13) 1123 1124 ``header-rows`` : integer_ 1125 The number of rows of list data to use in the table header. 1126 Defaults to 0. 1127 1128 ``stub-columns`` : integer_ 1129 The number of table columns to use as stubs (row titles, on the 1130 left). Defaults to 0. 1131 1132 .. _table width: 1133 1134 ``width`` : length_ or percentage_ of the current line width 1135 The width of the table. 1136 By default, the renderer determines the width of a table 1137 from its contents. [#width-from-widths2]_ 1138 1139 ``widths`` : `list of integers`_ or "auto" 1140 A list of relative column widths. The special value 1141 "auto" delegates the determination of column widths to the backend 1142 (LaTeX, the HTML browser, ...). 1143 1144 The default depends on the writer. 1145 The HTML5_ and manpage_ writers default to *"auto"*, the html4_ and 1146 LaTeX_ writers default to equal-width columns. [#widths-default]_ 1147 1148 .. TODO 1149 Add option ``missing-cells`` with keywords "strict", "fill", "span"? 1150 (cf. [feature-requests:#103]) 1151 1152 1153 ---------------- 1154 Document Parts 1155 ---------------- 1156 1157 .. A ``_contents:`` hyperlink here became id "contents-1" 1158 (name clash with the generated ToC) 1159 1160 Table of Contents 1161 ================= 1162 1163 .. class:: field-indent-13em 1164 1165 :Directive Type: "contents" 1166 :Doctree Elements: `\<pending>`_, `\<topic>`_ 1167 :Directive Arguments: one, optional: title 1168 :Directive Options: `see below <contents options_>`__ 1169 :Directive Content: none 1170 :Configuration Settings: toc_backlinks_, use_latex_toc_, generate_oowriter_toc_ 1171 1172 The "contents" directive generates a table of contents (TOC) in 1173 a `\<topic>`_ element. Topics, and therefore tables of contents, 1174 may occur anywhere a section or transition may occur. 1175 Body elements and topics may not contain tables of contents. 1176 1177 Here's the directive in its simplest form:: 1178 1179 .. contents:: 1180 1181 Language-dependent boilerplate text will be used for the title. The 1182 English default title text is "Contents". 1183 1184 An explicit title may be specified:: 1185 1186 .. contents:: Table of Contents 1187 1188 The title may span lines, although it is not recommended:: 1189 1190 .. contents:: Here's a very long Table of 1191 Contents title 1192 1193 Directive options may be specified using a field list:: 1194 1195 .. contents:: Table of Contents 1196 :depth: 2 1197 1198 If the default title is to be used, the options field list may begin 1199 on the same line as the directive marker:: 1200 1201 .. contents:: :depth: 2 1202 1203 .. _contents options: 1204 1205 The "contents" directive recognizes the common option 1206 `class <class option_>`_ as well as 1207 1208 ``backlinks`` : "entry" or "top" or "none" 1209 Generate links from section headers back to the table of contents 1210 entries, the table of contents itself, or generate no back-links. 1211 1212 ``depth`` : integer_ 1213 The number of section levels that are collected in the table of 1214 contents. The default is unlimited depth. 1215 1216 ``local`` : flag_ 1217 Generate a local table of contents. Entries will only include 1218 subsections of the section in which the directive is given. If no 1219 explicit title is given, the table of contents will not be titled. 1220 1221 1222 .. _sectnum: 1223 1224 Automatic Section Numbering 1225 =========================== 1226 1227 .. class:: field-indent-13em 1228 1229 :Directive Type: "sectnum" or "section-numbering" (synonyms) 1230 :Doctree Elements: `\<pending>`_, `\<generated>`_ 1231 :Directive Arguments: none 1232 :Directive Options: `see below <sectnum options_>`__ 1233 :Directive Content: none 1234 :Configuration Setting: sectnum_xform_ 1235 1236 The "sectnum" (or "section-numbering") directive automatically numbers 1237 sections and subsections in a document (if not disabled by the 1238 ``--no-section-numbering`` command line option or the `sectnum_xform`_ 1239 configuration setting). 1240 1241 Section numbers are of the "multiple enumeration" form, where each 1242 level has a number, separated by periods. For example, the title of section 1243 1, subsection 2, subsubsection 3 would have "1.2.3" prefixed. 1244 1245 The directive does its work in two passes: the initial parse 1246 and a transform. During the initial parse, a <pending> element is 1247 generated which acts as a placeholder, storing any options internally. 1248 At a later stage in the processing, the <pending> element triggers a 1249 transform, which adds section numbers to titles. Section numbers are 1250 enclosed in a <generated> element, and titles have their `auto attribute`_ 1251 set to "1". 1252 1253 .. _sectnum options: 1254 1255 The "sectnum" directive recognizes the following options: 1256 1257 ``depth`` : integer_ 1258 The number of section levels that are numbered by this directive. 1259 The default is unlimited depth. 1260 1261 ``prefix`` : text_ 1262 An arbitrary string that is prefixed to the automatically 1263 generated section numbers. It may be something like "3.2.", which 1264 will produce "3.2.1", "3.2.2", "3.2.2.1", and so on. Note that 1265 any separating punctuation (in the example, a period, ".") must be 1266 explicitly provided. The default is no prefix. 1267 1268 ``suffix`` : text_ 1269 An arbitrary string that is appended to the automatically 1270 generated section numbers. The default is no suffix. 1271 1272 ``start`` : integer_ 1273 The value that will be used for the first section number. 1274 Combined with ``prefix``, this may be used to force the right 1275 numbering for a document split over several source files. The 1276 default is 1. 1277 1278 1279 .. _header: 1280 .. _footer: 1281 1282 Document Header & Footer 1283 ======================== 1284 1285 :Directive Types: "header" and "footer" 1286 :Doctree Elements: `\<decoration>`_, `\<header>`_, `\<footer>`_ 1287 :Directive Arguments: none 1288 :Directive Options: none 1289 :Directive Content: Interpreted as body elements. 1290 1291 The "header" and "footer" directives create document decorations, 1292 useful for page navigation, notes, time/datestamp, etc. For example:: 1293 1294 .. header:: This space for rent. 1295 1296 This will add a paragraph to the document header, which will appear at 1297 the top of the generated web page or at the top of every printed page. 1298 1299 These directives may be used multiple times, cumulatively. There is 1300 currently support for only one header and footer. 1301 1302 .. tip:: 1303 1304 While it is possible to use the "header" and "footer" directives to 1305 create navigational elements for web pages, you should be aware 1306 that Docutils is meant to be used for *document* processing, and 1307 that a navigation bar is not typically part of a document. 1308 1309 Thus, you may soon find Docutils' abilities to be insufficient for 1310 these purposes. At that time, you should consider using a 1311 documentation generator like Sphinx_ rather than the "header" and 1312 "footer" directives. 1313 1314 In addition to the use of these directives to populate header and 1315 footer content, content may also be added automatically by the 1316 processing system. For example, if certain runtime settings are 1317 enabled, the document footer is populated with processing information 1318 such as a datestamp, a link to `the Docutils website`_, etc. 1319 1320 .. _the Docutils website: https://docutils.sourceforge.io 1321 1322 1323 ------------ 1324 References 1325 ------------ 1326 1327 .. _target-notes: 1328 1329 Target Footnotes 1330 ================ 1331 1332 .. class:: field-indent-13em 1333 1334 :Directive Type: "target-notes" 1335 :Doctree Elements: `\<pending>`_, `\<footnote>`_, `\<footnote_reference>`_ 1336 :Directive Arguments: none 1337 :Directive Options: `class <class option_>`_ 1338 :Directive Content: none 1339 1340 The "target-notes" directive generates a list of referenced URIs. 1341 This ensures the information is not lost in a hardcopy. 1342 1343 For every explicit [#]_ `external hyperlink target`_ in the document, 1344 the "target-notes" directive inserts a `\<footnote>`_ showing the URL 1345 at the place of the directive and a `\<footnote_reference>`_ after each 1346 matching `hyperlink reference`_. 1347 1348 The value of the `class option`_ is passed to the generated footnote 1349 references. 1350 1351 .. [#] `Embedded URIs`_ like ```this <http://example.org>`_`` are skipped. 1352 1353 1354 Footnotes 1355 ========= 1356 1357 **NOT IMPLEMENTED YET** 1358 1359 .. class:: field-indent-13em 1360 1361 :Directive Type: "footnotes" 1362 :Doctree Elements: `\<pending>`_, `\<topic>`_ 1363 :Directive Arguments: none? 1364 :Directive Options: Possible? 1365 :Directive Content: none 1366 1367 @@@ 1368 1369 1370 Citations 1371 ========= 1372 1373 **NOT IMPLEMENTED YET** 1374 1375 .. class:: field-indent-13em 1376 1377 :Directive Type: "citations" 1378 :Doctree Elements: `\<pending>`_, `\<topic>`_ 1379 :Directive Arguments: none? 1380 :Directive Options: Possible? 1381 :Directive Content: none 1382 1383 @@@ 1384 1385 .. --------------- 1386 HTML-Specific 1387 --------------- 1388 1389 Imagemap 1390 ======== 1391 1392 **NOT IMPLEMENTED YET** 1393 1394 Non-standard element: imagemap. 1395 1396 1397 ----------------------------------------- 1398 Directives for Substitution Definitions 1399 ----------------------------------------- 1400 1401 The directives introduced in this section may only be used in 1402 `substitution definitions`_. They may not be used directly, 1403 in standalone context. 1404 1405 .. _substitution definitions: 1406 .. _substitution definition: restructuredtext.html#substitution-definitions 1407 1408 1409 Inline Images 1410 ============= 1411 1412 The `image`_ directive can be used both, stand-alone (to define 1413 block-level images) and in substitution definitions to define 1414 inline images. 1415 1416 1417 .. _replace: 1418 1419 Replacement Text 1420 ================ 1421 1422 .. class:: field-indent-13em 1423 1424 :Directive Type: "replace" 1425 :Doctree Element: Text & `inline elements`_ 1426 :Directive Arguments: none 1427 :Directive Options: none 1428 :Directive Content: A single paragraph; may contain inline markup. 1429 1430 The "replace" directive is used to indicate replacement text for a 1431 substitution reference. It may be used within `substitution 1432 definitions`_ only. For example, this directive can be used to expand 1433 abbreviations:: 1434 1435 .. |reST| replace:: reStructuredText 1436 1437 Yes, |reST| is a long word, so I can't blame anyone for wanting to 1438 abbreviate it. 1439 1440 .. _hyperlink workaround: 1441 1442 As reStructuredText doesn't support nested inline markup, the only way 1443 to create a reference with styled text is to use substitutions with 1444 the "replace" directive:: 1445 1446 I recommend you try |Python|_. 1447 1448 .. |Python| replace:: Python, *the* best language around 1449 .. _Python: https://www.python.org/ 1450 1451 1452 .. _unicode: 1453 1454 Unicode Character Codes 1455 ======================= 1456 1457 .. class:: field-indent-13em 1458 1459 :Directive Type: "unicode" 1460 :Doctree Element: Text 1461 :Directive Arguments: one or more, required (Unicode character codes, 1462 optional text, and comments) 1463 :Directive Options: `see below <unicode options_>`__ 1464 :Directive Content: none 1465 1466 The "unicode" directive converts Unicode character codes (numerical 1467 values) to characters, and may be used in `substitution definitions`_ 1468 only. 1469 1470 The arguments, separated by spaces, can be: 1471 1472 .. _character code: 1473 1474 * **character codes** as 1475 1476 - decimal numbers or 1477 1478 - hexadecimal numbers, prefixed by ``0x``, ``x``, ``\x``, ``U+``, 1479 ``u``, or ``\u`` or as XML-style hexadecimal character entities, 1480 e.g. ``ᨫ`` 1481 1482 * **text**, which is used as-is. 1483 1484 Text following " .. " is a comment and is ignored. The spaces between 1485 the arguments are ignored and thus do not appear in the output. 1486 Hexadecimal codes are case-insensitive. 1487 1488 For example, the following text:: 1489 1490 Copyright |copy| 2003, |BogusMegaCorp (TM)| |---| 1491 all rights reserved. 1492 1493 .. |copy| unicode:: 0xA9 .. copyright sign 1494 .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 1495 .. with trademark sign 1496 .. |---| unicode:: U+02014 .. em dash 1497 :trim: 1498 1499 results in: 1500 1501 Copyright |copy| 2003, |BogusMegaCorp (TM)| |---| 1502 all rights reserved. 1503 1504 .. |copy| unicode:: 0xA9 .. copyright sign 1505 .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 1506 .. with trademark sign 1507 .. |---| unicode:: U+02014 .. em dash 1508 :trim: 1509 1510 Docutils comes with a set of character substitution 1511 definitions in the `reStructuredText Standard Definition Files`_. 1512 1513 .. _unicode options: 1514 1515 The "unicode" directive recognizes the following options: 1516 1517 ``ltrim`` : flag_ 1518 Whitespace to the left of the substitution reference is removed. 1519 1520 ``rtrim`` : flag_ 1521 Whitespace to the right of the substitution reference is removed. 1522 1523 ``trim`` : flag_ 1524 Equivalent to ``ltrim`` plus ``rtrim``; whitespace on both sides 1525 of the substitution reference is removed. 1526 1527 1528 Date 1529 ==== 1530 1531 .. class:: field-indent-13em 1532 1533 :Directive Type: "date" 1534 :Doctree Element: Text 1535 :Directive Arguments: one, optional (date format) 1536 :Directive Options: none 1537 :Directive Content: none 1538 1539 The "date" directive generates the current local date and inserts it 1540 into the document as text. This directive may be used in substitution 1541 definitions only. 1542 1543 The optional directive content is interpreted as the desired date 1544 format, using the same codes as Python's `time.strftime()`__ function. The 1545 default format is "%Y-%m-%d" (ISO 8601 date), but time fields can also 1546 be used. Examples:: 1547 1548 .. |date| date:: 1549 .. |time| date:: %H:%M 1550 1551 Today's date is |date|. 1552 1553 This document was generated on |date| at |time|. 1554 1555 __ https://docs.python.org/3/library/time.html#time.strftime 1556 1557 1558 --------------- 1559 Miscellaneous 1560 --------------- 1561 1562 .. _include: 1563 1564 Including an External Document Fragment 1565 ======================================= 1566 1567 .. class:: field-indent-13em 1568 1569 :Directive Type: "include" 1570 :Doctree Elements: Depend on data being included; 1571 `\<literal_block>`_ with ``code`` or ``literal`` option. 1572 :Directive Arguments: one, required (path_ to the file to include) 1573 :Directive Options: `see below <include options_>`__ 1574 :Directive Content: none 1575 :Configuration Setting: file_insertion_enabled_, root_prefix_ 1576 1577 .. WARNING:: 1578 1579 The "include" directive represents a potential security hole. It 1580 can be disabled with the "file_insertion_enabled_" runtime setting. 1581 1582 The "include" directive reads a text file. The directive argument is 1583 the path to the file to be included, relative to the document containing 1584 the directive. Unless the options ``literal``, ``code``, or ``parser`` 1585 are given, the file is parsed in the current document's context at the 1586 point of the directive. For example:: 1587 1588 This first example will be parsed at the document level, and can 1589 thus contain any construct, including section headers. 1590 1591 .. include:: inclusion.rst 1592 1593 Back in the main document. 1594 1595 This second example will be parsed in a block quote context. 1596 Therefore it may only contain body elements. It may not 1597 contain section headers. 1598 1599 .. include:: inclusion.rst 1600 1601 If an included document fragment contains section structure, the title 1602 adornments must match those of the master document. 1603 1604 Standard data files intended for inclusion in reStructuredText 1605 documents are distributed with the Docutils source code, located in 1606 the "docutils" package in the ``docutils/parsers/rst/include`` 1607 directory. To access these files, use the special syntax for standard 1608 "include" data files, angle brackets around the file name:: 1609 1610 .. include:: <isonum.txt> 1611 1612 The current set of standard "include" data files consists of sets of 1613 substitution definitions. See `reStructuredText Standard Definition 1614 Files`_ for details. 1615 1616 .. _include options: 1617 1618 The "include" directive recognizes the following options: 1619 1620 ``code`` : text_ (formal language, optional) 1621 The argument and the included content are passed to 1622 the code_ directive (useful for program listings). 1623 1624 ``encoding`` : encoding_ 1625 The text encoding of the external file. 1626 Defaults to the document's input_encoding_. 1627 1628 ``end-before`` : text_ 1629 Only the content before the first occurrence of the specified *text* 1630 in the external data file (but after any ``start-after`` text) 1631 will be included. 1632 1633 ``end-line`` : integer_ 1634 Only the content up to (but excluding) this line will be included. 1635 1636 ``literal`` : flag_ 1637 The entire included text is inserted into the document as a single 1638 literal block. 1639 1640 ``number-lines`` : integer_ (start line number, optional) 1641 Precede every included line with a line number. 1642 The optional argument is the number of the first line (default 1). 1643 Works only with ``code`` or ``literal``. 1644 1645 ``parser`` : text_ (parser name) 1646 Parse the included content with the specified parser. 1647 See the `"parser" configuration setting`_ for available parsers. 1648 1649 .. Caution:: 1650 There is is no check whether the inserted elements are valid at the 1651 point of insertion. It is recommended to validate_ the document. 1652 1653 (New in Docutils 0.17. Provisional.) 1654 1655 ``start-after`` : text_ 1656 Only the content after the first occurrence of the specified *text* 1657 in the external data file will be included. 1658 1659 ``start-line`` : integer_ 1660 Only the content starting from this line will be included. 1661 (As usual in Python, the first line has index 0 and negative values 1662 count from the end.) 1663 1664 ``tab-width`` : integer_ 1665 Number of spaces for hard tab expansion. 1666 Must be a positive integer, except for literal inclusions and code, 1667 where a negative value prevents expansion of hard tabs. 1668 Defaults to the tab_width_ configuration setting. 1669 1670 With ``code`` or ``literal``, the common options `class <class option_>`_ 1671 and name_ are recognized as well. 1672 1673 Combining ``start-line``/``end-line`` and ``start-after``/``end-before`` 1674 is possible. The text markers will be searched in the specified lines 1675 (further limiting the included content). 1676 1677 1678 .. _raw: 1679 1680 Raw Data Pass-Through 1681 ===================== 1682 1683 .. class:: field-indent-13em 1684 1685 :Directive Type: "raw" 1686 :Doctree Element: `\<raw>`_ 1687 :Directive Arguments: one or more, required (output format types) 1688 :Directive Options: `see below <raw options_>`__ 1689 :Directive Content: Stored verbatim, uninterpreted. 1690 None (empty) if a ``file`` or ``url`` option given. 1691 :Configuration Settings: raw_enabled_, file_insertion_enabled_, root_prefix_ 1692 1693 .. WARNING:: 1694 1695 The "raw" directive represents a potential security hole. It can 1696 be disabled with the "raw_enabled_" runtime setting. 1697 Insertion of external files can be disabled with the 1698 "file_insertion_enabled_" runtime setting. 1699 1700 .. Caution:: 1701 1702 The "raw" directive is a stop-gap measure allowing the author to 1703 bypass reStructuredText's markup. It is a "power-user" feature 1704 that should not be overused or abused. The use of "raw" ties 1705 documents to specific output formats and makes them less portable. 1706 1707 If you often need to use the "raw" directive or a "raw"-derived 1708 interpreted text role, that is a sign either of overuse/abuse or 1709 that functionality may be missing from reStructuredText. Please 1710 describe your situation in a message to the Docutils-users_ mailing 1711 list. 1712 1713 .. _Docutils-users: ../../user/mailing-lists.html#docutils-users 1714 1715 The "raw" directive indicates non-reStructuredText data that is to be 1716 passed untouched to the Writer. The names of the output formats are 1717 given in the directive arguments. The interpretation of the raw data 1718 is up to the Writer. A Writer may ignore any raw output not matching 1719 its format. 1720 1721 For example, the following input would be passed untouched by an HTML 1722 writer:: 1723 1724 .. raw:: html 1725 1726 <hr width=50 size=10> 1727 1728 A LaTeX Writer could insert the following raw content into its 1729 output stream:: 1730 1731 .. raw:: latex 1732 1733 \setlength{\parindent}{0pt} 1734 1735 Raw data can also be read from an external file, specified in the 1736 ``file`` or ``url`` directive option. 1737 In this case, the content block must be empty. 1738 For example:: 1739 1740 .. raw:: html 1741 :file: inclusion.html 1742 1743 Inline equivalents of the "raw" directive can be defined via 1744 `custom interpreted text roles`_ derived from the `"raw" role`_. 1745 1746 .. _raw options: 1747 1748 The "raw" directive recognizes the common option `class <class option_>`_ 1749 as well as 1750 1751 ``encoding`` : encoding_ 1752 The text encoding of the external raw data (with ``file`` or ``url``). 1753 Defaults to the main document's `input_encoding`_. 1754 1755 ``file`` : path_ 1756 The local filesystem path of a raw data file to be included. 1757 1758 ``url`` : URI_ 1759 A URI reference to a raw data file to be included. 1760 1761 1762 .. _class directive: 1763 .. _rst-class: 1764 1765 Class 1766 ===== 1767 1768 .. class:: field-indent-13em 1769 1770 :Directive Type: "class" or "rst-class" (synonyms) [#]_ 1771 :Doctree Element: `\<pending>`_ 1772 :Directive Arguments: one or more, required 1773 (class names / attribute values) 1774 :Directive Options: none 1775 :Directive Content: Optional. If present, it is interpreted as body 1776 elements. 1777 1778 The "class" directive sets the `classes attribute`_ value on its content 1779 or on the next visible [#]_ element. [#]_ 1780 The directive argument consists of one or more space-separated class 1781 names. The names are transformed to conform to the regular expression 1782 ``[a-z](-?[a-z0-9]+)*`` (see `Identifier Normalization`_ below). 1783 1784 .. tip:: For reStructuredText directives, the `class option`_ provides 1785 a more compact markup alternative. 1786 1787 Examples:: 1788 1789 .. class:: special 1790 1791 This is a "special" paragraph. 1792 1793 .. class:: exceptional remarkable 1794 1795 An Exceptional Section 1796 ====================== 1797 1798 This is an ordinary paragraph. 1799 1800 .. class:: multiple 1801 1802 First paragraph. 1803 1804 Second paragraph. 1805 1806 The text above is parsed and transformed into this doctree_ fragment:: 1807 1808 <paragraph classes="special"> 1809 This is a "special" paragraph. 1810 <section classes="exceptional remarkable"> 1811 <title> 1812 An Exceptional Section 1813 <paragraph> 1814 This is an ordinary paragraph. 1815 <paragraph classes="multiple"> 1816 First paragraph. 1817 <paragraph classes="multiple"> 1818 Second paragraph. 1819 1820 Indented text after the directive is interpreted as content block. 1821 To set a classes attribute value on a `block quote`_, the 1822 "class" directive must be followed by a comment:: 1823 1824 .. class:: special 1825 .. 1826 1827 Special block quote. 1828 1829 results in this doctree_ fragment:: 1830 1831 <comment xml:space="preserve"> 1832 <block_quote classes="special"> 1833 <paragraph> 1834 Special block quote. 1835 1836 .. [#] Sphinx_ uses the directive name "class" for `domain specific`__ 1837 directives (by default "`py:class`__"). 1838 The "rst-class" synonym is compatible with Sphinx. 1839 1840 __ https://www.sphinx-doc.org/en/master/usage/domains/ 1841 __ https://www.sphinx-doc.org/en/master/usage/domains/python.html 1842 #directive-py-class 1843 1844 .. [#] Elements that are not shown in the output (comments_, 1845 `substitution definitions`_, `hyperlink targets`_, ...) as well as 1846 "header_" and "footer_" directives are skipped. 1847 1848 .. [#] This also works if the class directive is "nested" at the end of 1849 an indented text block. 1850 This allows the "classification" of individual list items (except the 1851 first, as a preceding class directive applies to the list as a whole):: 1852 1853 * bullet list 1854 1855 .. class:: classy-item 1856 1857 * second item, with class argument 1858 1859 1860 Identifier Normalization 1861 ~~~~~~~~~~~~~~~~~~~~~~~~ 1862 1863 Docutils normalizes `class names`_ and `identifiers`_ to conform 1864 to the regular expression "``[a-z](-?[a-z0-9]+)*``" by converting 1865 1866 * alphabetic characters to lowercase, 1867 * accented characters to the base character, 1868 * non-alphanumeric characters to hyphens, 1869 * consecutive hyphens into one hyphen 1870 1871 and stripping 1872 1873 * leading hyphens and number characters, and 1874 * trailing hyphens. 1875 1876 For example ``"Rot.Gelb&Grün::2008+"`` becomes ``"rot-gelb-grun-2008"`` and 1877 ``"1000_Steps!"`` becomes ``"steps"``. 1878 1879 .. topic:: Rationale: 1880 1881 Identifier keys must be valid in all supported output formats. 1882 1883 For HTML 4.1 + CSS1 compatibility, identifiers should have no 1884 underscores, colons, or periods. Hyphens may be used. 1885 1886 - The `HTML 4.01 spec`_ defines identifiers based on SGML tokens: 1887 1888 ID and NAME tokens must begin with a letter ([A-Za-z]) and 1889 may be followed by any number of letters, digits ([0-9]), 1890 hyphens ("-"), underscores ("_"), colons (":"), and periods 1891 ("."). 1892 1893 -- https://www.w3.org/TR/html401/types.html#type-name 1894 1895 - The `CSS1 spec`_ defines identifiers based on the "name" token 1896 ("flex" tokenizer notation below):: 1897 1898 unicode \\[0-9a-f]{1,4} 1899 latin1 [¡-ÿ] 1900 escape {unicode}|\\[ -~¡-ÿ] 1901 nmchar [-a-z0-9]|{latin1}|{escape} 1902 name {nmchar}+ 1903 1904 The CSS1 rule requires underscores ("_"), colons (":"), and 1905 periods (".") to be escaped [#]_, 1906 therefore `classes`_ and `ids attribute`_\ s should not 1907 contain these characters. Combined with HTML4.1 requirements (the 1908 first character must be a letter; no "unicode", "latin1", or 1909 "escape" characters), this results in the regular expression 1910 ``[A-Za-z][-A-Za-z0-9]*``. Docutils adds a normalization by 1911 downcasing and merge of consecutive hyphens. 1912 1913 .. [#] CSS identifiers may use underscores ("_") directly in 1914 `CSS Level 1`__, `CSS2.1`__, CSS2.2__, and CSS3__. 1915 1916 __ https://www.w3.org/TR/CSS21/syndata.html#value-def-identifier 1917 __ https://www.w3.org/TR/CSS/#css-level-1 1918 __ https://www.w3.org/TR/CSS22/syndata.html 1919 __ https://www.w3.org/TR/css-syntax-3/#typedef-ident-token 1920 1921 .. _HTML 4.01 spec: https://www.w3.org/TR/html401/ 1922 .. _CSS1 spec: https://www.w3.org/TR/REC-CSS1 1923 1924 1925 .. _role: 1926 1927 Custom Interpreted Text Roles 1928 ============================= 1929 1930 .. class:: field-indent-13em 1931 1932 :Directive Type: "role" 1933 :Doctree Element: none; affects subsequent parsing 1934 :Directive Arguments: two; one required (new `role name`_), one optional 1935 (base role name, in parentheses) 1936 :Directive Options: `see below <role options_>`__ 1937 :Directive Content: depends on base role. 1938 1939 The "role" directive dynamically creates a custom `interpreted text 1940 role`_ and registers it with the parser. This means that after 1941 declaring a role like this:: 1942 1943 .. role:: custom 1944 1945 the document may use the new "custom" role:: 1946 1947 An example of using :custom:`interpreted text` 1948 1949 This will be parsed into the following document tree fragment:: 1950 1951 <paragraph> 1952 An example of using 1953 <inline classes="custom"> 1954 interpreted text 1955 1956 .. _role name: 1957 1958 *Role names* are case insensitive and must conform to the rules of 1959 simple `reference names`_ (but do not share a namespace with 1960 hyperlinks, footnotes, and citations). 1961 1962 The new role may be based on an existing role, specified as a second 1963 argument in parentheses (whitespace optional):: 1964 1965 .. role:: custom(emphasis) 1966 1967 :custom:`text` 1968 1969 The parsed result is as follows:: 1970 1971 <paragraph> 1972 <emphasis classes="custom"> 1973 text 1974 1975 A special case is the `"raw" role`_: derived roles enable 1976 inline `raw data pass-through`_, e.g.:: 1977 1978 .. role:: raw-role(raw) 1979 :format: html latex 1980 1981 :raw-role:`raw text` 1982 1983 If no base role is explicitly specified, a generic custom role is 1984 automatically used. Subsequent interpreted text will produce an 1985 `\<inline>`_ element with a `classes attribute`_, as in the first 1986 example above. 1987 1988 .. _role options: 1989 1990 Depending on the base role, the following options may be recognized by the 1991 "role" directive: 1992 1993 .. _role directive class option: 1994 1995 class : space separated list of `class names`_ 1996 Set the `classes attribute`_ value on the element produced 1997 when the custom interpreted text role is used. 1998 Default value is the directive argument (role name). 1999 2000 For example :: 2001 2002 .. role:: custom 2003 :class: special 2004 2005 :custom:`interpreted text` 2006 2007 is parsed as :: 2008 2009 <paragraph> 2010 <inline classes="special"> 2011 interpreted text 2012 2013 The "class" option is recognized with all interpreted text roles. 2014 2015 _`format` : space-separated list of output format names (`writer names`_) 2016 Specify the generated <raw> element's `format attribute`_. 2017 2018 Only recognized with the `"raw" <"raw" role_>`__ base role. 2019 2020 _`language` : text_ (formal language) 2021 Name of a formal language, passed to Pygments_ for syntax highlighting. 2022 See `supported languages and markup formats`_ for recognized values. 2023 2024 Only recognized with the `"code" <"code" role>`__ base role. 2025 2026 .. _writer names: ../../user/config.html#writer-docutils-application 2027 2028 2029 .. _default-role: 2030 2031 Setting the Default Interpreted Text Role 2032 ========================================= 2033 2034 .. class:: field-indent-13em 2035 2036 :Directive Type: "default-role" 2037 :Doctree Element: none; affects subsequent parsing 2038 :Directive Arguments: one, optional (new default role name) 2039 :Directive Options: none 2040 :Directive Content: none 2041 2042 The "default-role" directive sets the default interpreted text role, 2043 the role that is used for interpreted text without an explicit role. 2044 For example, after setting the default role like this:: 2045 2046 .. default-role:: subscript 2047 2048 any subsequent use of implicit-role interpreted text in the document 2049 will use the "subscript" role:: 2050 2051 An example of a `default` role. 2052 2053 This will be parsed into the following document tree fragment:: 2054 2055 <paragraph> 2056 An example of a 2057 <subscript> 2058 default 2059 role. 2060 2061 Custom roles may be used (see the "role_" directive above), but it 2062 must have been declared in a document before it can be set as the 2063 default role. See the `reStructuredText Interpreted Text Roles`_ 2064 document for details of built-in roles. 2065 2066 The directive may be used without an argument to restore the initial 2067 default interpreted text role, which is application-dependent. The 2068 initial default interpreted text role of the standard reStructuredText 2069 parser is "title-reference". 2070 2071 2072 .. _meta: 2073 2074 Metadata 2075 ======== 2076 2077 .. class:: field-indent-13em 2078 2079 :Directive Type: "meta" 2080 :Doctree Element: `\<meta>`_ 2081 :Directive Arguments: none 2082 :Directive Options: none 2083 :Directive Content: Must contain a flat `field list`_. 2084 2085 The "meta" directive is used to specify metadata [#]_ to be stored 2086 in, e.g., `HTML meta elements`_ or as `ODT file properties`_. The 2087 LaTeX writer passes it to the ``pdfinfo`` option of the hyperref_ 2088 package. If an output format does not support "invisible" metadata, 2089 content is silently dropped by the writer. 2090 2091 .. note:: Data from some `bibliographic fields`_ is automatically 2092 extracted and stored as metadata, too. However, Bibliographic 2093 Fields are also displayed in the document's screen rendering or 2094 printout. 2095 2096 For an "invisible" *document title*, see the `metadata document 2097 title`_ directive below. 2098 2099 Within the directive block, a flat field list provides the syntax for 2100 metadata. The field name becomes the contents of the "name" attribute 2101 of the META tag, and the field body (interpreted as a single string 2102 without inline markup) becomes the contents of the "content" 2103 attribute. For example:: 2104 2105 .. meta:: 2106 :description: The reStructuredText plaintext markup language 2107 :keywords: plaintext, markup language 2108 2109 This would be converted to the following HTML:: 2110 2111 <meta name="description" 2112 content="The reStructuredText plaintext markup language"> 2113 <meta name="keywords" content="plaintext, markup language"> 2114 2115 Support for other META attributes ("http-equiv", "scheme", "lang", 2116 "dir") are provided through field arguments, which must be of the form 2117 "attr=value":: 2118 2119 .. meta:: 2120 :description lang=en: An amusing story 2121 :description lang=fr: Une histoire amusante 2122 2123 And their HTML equivalents:: 2124 2125 <meta name="description" lang="en" content="An amusing story"> 2126 <meta name="description" lang="fr" content="Une histoire amusante"> 2127 2128 Some META tags use an "http-equiv" attribute instead of the "name" 2129 attribute. To specify "http-equiv" META tags, simply omit the name:: 2130 2131 .. meta:: 2132 :http-equiv=Content-Type: text/html; charset=ISO-8859-1 2133 2134 HTML equivalent:: 2135 2136 <meta http-equiv="Content-Type" 2137 content="text/html; charset=ISO-8859-1"> 2138 2139 .. [#] "Metadata" is data about data, in this case data about the 2140 document. Metadata is, e.g., used to describe and classify web 2141 pages in the World Wide Web, in a form that is easy for search 2142 engines to extract and collate. 2143 2144 .. _HTML meta elements: 2145 https://html.spec.whatwg.org/multipage/semantics.html#the-meta-element 2146 .. _ODT file properties: 2147 https://en.wikipedia.org/wiki/OpenDocument_technical_specification#Metadata 2148 .. _hyperref: https://ctan.org/pkg/hyperref 2149 .. _bibliographic fields: restructuredtext.html#bibliographic-fields 2150 .. _field list: restructuredtext.html#field-lists 2151 2152 2153 .. _title: 2154 2155 Metadata Document Title 2156 ======================= 2157 2158 .. class:: field-indent-13em 2159 2160 :Directive Type: "title" 2161 :Doctree Element: sets the `\<document>`_ element's `title attribute`_) 2162 :Directive Arguments: one, required (the title text) 2163 :Directive Options: none 2164 :Directive Content: none 2165 :Configuration Setting: `title <"title" configuration setting_>`__ 2166 2167 The "title" directive specifies the document title as metadata, which 2168 does not become part of the document body. It overrides the 2169 document-supplied `document title`_ and the `"title" configuration 2170 setting`_. 2171 2172 2173 Restructuredtext-Test-Directive 2174 =============================== 2175 2176 .. class:: field-indent-13em 2177 2178 :Directive Type: "restructuredtext-test-directive" 2179 :Doctree Element: `\<system_message>`_ 2180 :Directive Arguments: none 2181 :Directive Options: none 2182 :Directive Content: Interpreted as a literal block. 2183 2184 This directive is provided for test purposes only. (Nobody is 2185 expected to type in a name *that* long!) It is converted into a 2186 level-1 (info) system message showing the directive data, possibly 2187 followed by a literal block containing the rest of the directive 2188 block. 2189 2190 2191 -------------- 2192 Common Options 2193 -------------- 2194 2195 Most of the directives that generate doctree elements support the following 2196 options: 2197 2198 .. _class option: 2199 2200 ``class`` : text_ (space separated list of `class names`_) 2201 Set a `classes attribute`_ value on the doctree element generated by 2202 the directive. For example, :: 2203 2204 .. image:: bild.png 2205 :alt: example picture 2206 :class: large-pics 2207 2208 is the recommended syntax alternative to a preceding 2209 `class directive`_ :: 2210 2211 .. class:: large-pics 2212 .. image:: bild.png 2213 :alt: example picture 2214 2215 .. _`name`: 2216 2217 ``name`` : text_ 2218 Add *text* to the `names attribute`_ of the doctree element generated 2219 by the directive. This allows `hyperlink references`_ to the element 2220 using `text` as `reference name`_. For example, :: 2221 2222 .. image:: bild.png 2223 :alt: example picture 2224 :name: my picture 2225 2226 is the recommended syntax alternative to a preceding 2227 `hyperlink target`_ :: 2228 2229 .. _my picture: 2230 .. image:: bild.png 2231 :alt: example picture 2232 2233 2234 ------------------------- 2235 Common Option Value Types 2236 ------------------------- 2237 2238 .. class:: run-in narrow 2239 2240 :"keyword": recognized keywords 2241 2242 Used without quotes in the reStructuredText source. 2243 2244 :_`character`: single character 2245 2246 May be specified as literal character or as Unicode `character code`_ 2247 (cf. the unicode_ directive). 2248 2249 :_`encoding`: text encoding name 2250 2251 Docutils looks it up in the list of registered codecs_ 2252 (see also `Standard Encodings`_). 2253 2254 :_`flag`: no value 2255 2256 :_`integer`: integer number 2257 2258 A _`list of integers` may be comma- or whitespace-separated. 2259 2260 :_`length`: number, optionally followed by one of the 2261 `supported length units`_ 2262 2263 Handling of values without unit depends on the writer/output format. 2264 See the writer specific documentation in the `user doc`__ for details. 2265 2266 __ ../../index.html#introductory-tutorial-material-for-end-users 2267 2268 :_`path`: local filesystem path 2269 2270 Newlines are removed. 2271 The `root_prefix`_ configuration setting can be used to tell Docutils 2272 to interpret paths starting with "/" relative to a "project directory". 2273 2274 :_`percentage`: number followed by the percent sign '%' 2275 2276 Percentage values are relative to other values, depending on the 2277 context in which they occur. 2278 2279 :_`text`: free text 2280 2281 Possible restrictions are given in parentheses. 2282 2283 :_`URI`: _`URI reference` 2284 2285 Full URI or `relative reference`_ 2286 (absolute or relative path reference, cf. :RFC:`3986`). 2287 Whitespace is removed (cf. `external hyperlink targets`_ in the 2288 reStructuredText specification). 2289 2290 .. References 2291 2292 .. _codecs: https://docs.python.org/3/library/codecs.html 2293 .. _relative reference: https://www.rfc-editor.org/rfc/rfc3986.html#section-4.2 2294 .. _Sphinx: http://sphinx-doc.org/ 2295 .. _Standard Encodings: 2296 https://docs.python.org/3/library/codecs.html#standard-encodings 2297 2298 .. _reStructuredText Markup Specification: restructuredtext.html 2299 .. _block quote: restructuredtext.html#block-quotes 2300 .. _comments: restructuredtext.html#comments 2301 .. _directives: restructuredtext.html#directives 2302 .. _document title: restructuredtext.html#document-title 2303 .. _embedded URIs: restructuredtext.html#embedded-uris-and-aliases 2304 .. _escaping mechanism: restructuredtext.html#escaping-mechanism 2305 .. _external hyperlink target: 2306 .. _external hyperlink targets: 2307 restructuredtext.html#external-hyperlink-targets 2308 .. _grid table: restructuredtext.html#grid-tables 2309 .. _hyperlink reference: 2310 .. _hyperlink references: restructuredtext.html#hyperlink-references 2311 .. _hyperlink targets: 2312 .. _hyperlink target: restructuredtext.html#hyperlink-targets 2313 .. _supported length units: restructuredtext.html#length-units 2314 .. _reference name: 2315 .. _reference names: restructuredtext.html#reference-names 2316 .. _simple table: restructuredtext.html#simple-tables 2317 2318 .. _reStructuredText Interpreted Text Roles: 2319 .. _interpreted text role: roles.html 2320 .. _"code" role: roles.html#code 2321 .. _"math" role: roles.html#math 2322 .. _"raw" role: roles.html#raw 2323 2324 .. Docutils Configuration 2325 .. _file_insertion_enabled: ../../user/config.html#file-insertion-enabled 2326 .. _generate_oowriter_toc: ../../user/config.html#generate-oowriter-toc 2327 .. _image_loading: ../../user/config.html#image-loading 2328 .. _input_encoding: ../../user/config.html#input-encoding 2329 .. _math_output: ../../user/config.html#math-output 2330 .. _"parser" configuration setting: ../../user/config.html#parser 2331 .. _raw_enabled: ../../user/config.html#raw-enabled 2332 .. _root_prefix: ../../user/config.html#root-prefix 2333 .. _sectnum_xform: ../../user/config.html#sectnum-xform 2334 .. _syntax_highlight: ../../user/config.html#syntax-highlight 2335 .. _tab_width: ../../user/config.html#tab-width 2336 .. _table_style: ../../user/config.html#table-style 2337 .. _"title" configuration setting: ../../user/config.html#title 2338 .. _toc_backlinks: ../../user/config.html#toc-backlinks 2339 .. _use_latex_toc: ../../user/config.html#use-latex-toc 2340 .. _validate: ../../user/config.html#validate 2341 2342 .. _reStructuredText Standard Definition Files: definitions.html 2343 2344 .. _The Docutils Document Tree: 2345 .. _doctree: ../doctree.html 2346 .. _identifiers: ../doctree.html#identifiers 2347 .. _inline elements: ../doctree.html#inline-elements 2348 .. _class names: ../doctree.html#class-names 2349 .. _auto attribute: ../doctree.html#auto 2350 .. _classes: 2351 .. _classes attribute: ../doctree.html#classes 2352 .. _format attribute: ../doctree.html#format 2353 .. _ids attribute: ../doctree.html#ids 2354 .. _loading attribute: ../doctree.html#loading 2355 .. _names attribute: ../doctree.html#names 2356 .. _title attribute: ../doctree.html#title-attribute 2357 .. _width attribute: ../doctree.html#width 2358 .. _<admonition>: ../doctree.html#admonition 2359 .. _<attention>: ../doctree.html#attention 2360 .. _<block_quote>: ../doctree.html#block-quote 2361 .. _<caption>: ../doctree.html#caption 2362 .. _<caution>: ../doctree.html#caution 2363 .. _<compound>: ../doctree.html#compound 2364 .. _<container>: ../doctree.html#container 2365 .. _<danger>: ../doctree.html#danger 2366 .. _<decoration>: ../doctree.html#decoration 2367 .. _<document>: ../doctree.html#document 2368 .. _<error>: ../doctree.html#error 2369 .. _<figure>: ../doctree.html#figure 2370 .. _<footer>: ../doctree.html#footer 2371 .. _<footnote>: ../doctree.html#footnote 2372 .. _<footnote_reference>: ../doctree.html#footnote-reference 2373 .. _<generated>: ../doctree.html#generated 2374 .. _<header>: ../doctree.html#header 2375 .. _<hint>: ../doctree.html#hint 2376 .. _<image>: ../doctree.html#image 2377 .. _<inline>: ../doctree.html#inline 2378 .. _<important>: ../doctree.html#important 2379 .. _<legend>: ../doctree.html#legend 2380 .. _<line_block>: ../doctree.html#line-block 2381 .. _<literal_block>: ../doctree.html#literal-block 2382 .. _<math_block>: ../doctree.html#math-block 2383 .. _<meta>: ../doctree.html#meta 2384 .. _<note>: ../doctree.html#note 2385 .. _<pending>: ../doctree.html#pending 2386 .. _<raw>: ../doctree.html#raw 2387 .. _<reference>: ../doctree.html#reference 2388 .. _<rubric>: ../doctree.html#rubric 2389 .. _<sidebar>: ../doctree.html#sidebar 2390 .. _<system_message>: ../doctree.html#system-message 2391 .. _<table>: ../doctree.html#table 2392 .. _<tip>: ../doctree.html#tip 2393 .. _<title>: ../doctree.html#title 2394 .. _<topic>: ../doctree.html#topic 2395 .. _<warning>: ../doctree.html#warning 2396 2397 2398 .. Emacs settings 2399 2400 Local Variables: 2401 mode: indented-text 2402 mode: rst 2403 indent-tabs-mode: nil 2404 sentence-end-double-space: t 2405 fill-column: 70 2406 End: