1 =============================
2 reStructuredText Directives
3 =============================
5 :Contact: docutils-develop@lists.sourceforge.net
8 :Copyright: This document has been placed in the public domain.
13 This document describes the directives implemented in the reference
14 reStructuredText parser.
16 Directives have the following syntax::
18 +-------+-------------------------------+
19 | ".. " | directive type "::" directive |
22 +-------------------------------+
24 Directives begin with an explicit markup start (two periods and a
25 space), followed by the directive type and two colons (collectively,
26 the "directive marker"). The directive block begins immediately after
27 the directive marker, and includes all subsequent indented lines. The
28 directive block is divided into arguments, options (a field list), and
29 content (in that order), any of which may appear. See the Directives_
30 section in the `reStructuredText Markup Specification`_ for syntax
33 Descriptions below list "doctree elements" (document tree element
34 names; XML DTD generic identifiers) corresponding to individual
35 directives. For details on the hierarchy of elements, please see `The
36 Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document
37 type definition. For directive implementation details, see `Creating
38 reStructuredText Directives`_.
40 .. _Directives: restructuredtext.html#directives
41 .. _reStructuredText Markup Specification: restructuredtext.html
42 .. _The Docutils Document Tree: ../doctree.html
43 .. _Docutils Generic DTD: ../docutils.dtd
44 .. _Creating reStructuredText Directives:
45 ../../howto/rst-directives.html
52 .. From Webster's Revised Unabridged Dictionary (1913) [web1913]:
54 Gentle or friendly reproof; counseling against a fault or
55 error; expression of authoritative advice; friendly caution
58 Syn: {Admonition}, {Reprehension}, {Reproof}.
60 Usage: Admonition is prospective, and relates to moral delinquencies;
61 its object is to prevent further transgression.
76 :Directive Types: "attention", "caution", "danger", "error", "hint",
77 "important", "note", "tip", "warning", "admonition"
78 :Doctree Elements: attention, caution, danger, error, hint, important,
79 note, tip, warning, admonition_, title
80 :Directive Arguments: None.
81 :Directive Options: `:class:`_, `:name:`_
82 :Directive Content: Interpreted as body elements.
84 Admonitions are specially marked "topics" that can appear anywhere an
85 ordinary body element can. They contain arbitrary body elements.
86 Typically, an admonition is rendered as an offset block in a document,
87 sometimes outlined or shaded, with a title matching the admonition
91 Beware killer rabbits!
93 This directive might be rendered something like this::
95 +------------------------+
98 | Beware killer rabbits! |
99 +------------------------+
101 The following admonition directives have been implemented:
113 Any text immediately following the directive indicator (on the same
114 line and/or indented on following lines) is interpreted as a directive
115 block and is parsed for normal body elements. For example, the
116 following "note" admonition directive contains one paragraph and a
117 bullet list consisting of two list items::
119 .. note:: This is a note admonition.
120 This is the second line of the first paragraph.
122 - The note contains all indented body elements
124 - It includes this bullet list.
130 :Directive Type: "admonition"
131 :Doctree Elements: admonition_, title
132 :Directive Arguments: One, required (admonition title)
133 :Directive Options: Possible, see below.
134 :Directive Content: Interpreted as body elements.
136 This is a generic, titled admonition. The title may be anything the
139 The author-supplied title is also used as a `"classes"`_ attribute value
140 after being converted into a valid identifier form (down-cased;
141 non-alphanumeric characters converted to single hyphens; "admonition-"
142 prefixed). For example, this admonition::
144 .. admonition:: And, by the way...
146 You can make up your own admonition too.
148 becomes the following document tree (pseudo-XML)::
150 <document source="test data">
151 <admonition classes="admonition-and-by-the-way">
155 You can make up your own admonition too.
157 The `common options`_ are recognized:
160 Overrides the computed `"classes"`_ attribute value.
163 Add `text` to the `"names"`_ attribute of the admonition element.
170 There are two image directives: "image" and "figure".
176 :Directive Type: "image"
177 :Doctree Element: image_
178 :Directive Arguments: One, required (image URI).
179 :Directive Options: Possible.
180 :Directive Content: None.
182 An "image" is a simple picture::
184 .. image:: picture.png
186 Inline images can be defined with an "image" directive in a `substitution
189 The URI for the image source file is specified in the directive
190 argument. As with hyperlink targets, the image URI may begin on the
191 same line as the explicit markup start and target name, or it may
192 begin in an indented text block immediately following, with no
193 intervening blank lines. If there are multiple lines in the link
194 block, they are stripped of leading and trailing whitespace and joined
197 Optionally, the image link block may contain a flat field list, the
198 _`image options`. For example::
200 .. image:: picture.jpeg
207 The following options are recognized:
210 Alternate text: a short description of the image, displayed by
211 applications that cannot display images, or spoken by applications
212 for visually impaired users.
214 ``height`` : `length`_
215 The desired height of the image.
216 Used to reserve space or scale the image vertically. When the "scale"
217 option is also specified, they are combined. For example, a height of
218 200px and a scale of 50 is equivalent to a height of 100px with no scale.
220 ``width`` : `length`_ or `percentage`_ of the current line width
221 The width of the image.
222 Used to reserve space or scale the image horizontally. As with "height"
223 above, when the "scale" option is also specified, they are combined.
225 ``scale`` : integer percentage (the "%" symbol is optional)
226 The uniform scaling factor of the image. The default is "100 %", i.e.
229 If no "height" or "width" options are specified, the `Python Imaging
230 Library`_ (PIL) may be used to determine them, if it is installed and
231 the image file is available.
233 ``align`` : "top", "middle", "bottom", "left", "center", or "right"
234 The alignment of the image, equivalent to the HTML ``<img>`` tag's
235 deprecated "align" attribute or the corresponding "vertical-align" and
236 "text-align" CSS properties.
237 The values "top", "middle", and "bottom"
238 control an image's vertical alignment (relative to the text
239 baseline); they are only useful for inline images (substitutions).
240 The values "left", "center", and "right" control an image's
241 horizontal alignment, allowing the image to float and have the
242 text flow around it. The specific behavior depends upon the
243 browser or rendering software used.
245 ``target`` : text (URI or reference name)
246 Makes the image into a hyperlink reference ("clickable"). The
247 option argument may be a URI (relative or absolute), or a
248 `reference name`_ with underscore suffix (e.g. ```a name`_``).
250 and the common options `:class:`_ and `:name:`_.
256 :Directive Type: "figure"
257 :Doctree Elements: figure_, image_, caption_, legend_
258 :Directive Arguments: One, required (image URI).
259 :Directive Options: Possible.
260 :Directive Content: Interpreted as the figure caption and an optional
263 A "figure" consists of image_ data (including `image options`_), an optional
264 caption (a single paragraph), and an optional legend (arbitrary body
265 elements). For page-based output media, figures might float to a different
266 position if this helps the page layout.
269 .. figure:: picture.png
271 :alt: map to buried treasure
273 This is the caption of the figure (a simple paragraph).
275 The legend consists of all elements after the caption. In this
276 case, the legend consists of this paragraph and the following
279 +-----------------------+-----------------------+
281 +=======================+=======================+
282 | .. image:: tent.png | Campground |
283 +-----------------------+-----------------------+
284 | .. image:: waves.png | Lake |
285 +-----------------------+-----------------------+
286 | .. image:: peak.png | Mountain |
287 +-----------------------+-----------------------+
289 There must be blank lines before the caption paragraph and before the
290 legend. To specify a legend without a caption, use an empty comment
291 ("..") in place of the caption.
293 The "figure" directive supports all of the options of the "image"
294 directive (see `image options`_ above). These options (except
295 "align") are passed on to the contained image.
297 ``align`` : "left", "center", or "right"
298 The horizontal alignment of the figure, allowing the image to
299 float and have the text flow around it. The specific behavior
300 depends upon the browser or rendering software used.
302 In addition, the following options are recognized:
304 ``figwidth`` : "image", length_, or percentage_ of current line width
305 The width of the figure.
306 Limits the horizontal space used by the figure.
307 A special value of "image" is allowed, in which case the
308 included image's actual width is used (requires the `Python Imaging
309 Library`_). If the image file is not found or the required software is
310 unavailable, this option is ignored.
312 Sets the "width" attribute of the "figure" doctree element.
314 This option does not scale the included image; use the "width"
315 `image`_ option for that. ::
317 +---------------------------+
320 |<------ figwidth --------->|
322 | +---------------------+ |
325 | |<--- width --------->| |
326 | +---------------------+ |
328 |The figure's caption should|
329 |wrap at this width. |
330 +---------------------------+
333 Set a `"classes"`_ attribute value on the figure element. See the
334 class_ directive below.
336 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
346 :Directive Type: "topic"
347 :Doctree Element: topic_
348 :Directive Arguments: One, required (topic title).
349 :Directive Options: `:class:`_, `:name:`_
350 :Directive Content: Interpreted as the topic body.
352 A topic is like a block quote with a title, or a self-contained
353 section with no subsections. Use the "topic" directive to indicate a
354 self-contained idea that is separate from the flow of the document.
355 Topics may occur anywhere a section or transition may occur. Body
356 elements and topics may not contain nested topics.
358 The directive's sole argument is interpreted as the topic title; the
359 next line must be blank. All subsequent lines make up the topic body,
360 interpreted as body elements. For example::
362 .. topic:: Topic Title
364 Subsequent indented lines comprise
365 the body of the topic, and are
366 interpreted as body elements.
372 :Directive Type: "sidebar"
373 :Doctree Element: sidebar_
374 :Directive Arguments: One, optional (sidebar title).
375 :Directive Options: Possible (see below).
376 :Directive Content: Interpreted as the sidebar body.
378 Sidebars are like miniature, parallel documents that occur inside
379 other documents, providing related or reference material. A sidebar
380 is typically offset by a border and "floats" to the side of the page;
381 the document's main text may flow around it. Sidebars can also be
382 likened to super-footnotes; their content is outside of the flow of
383 the document's main text.
385 Sidebars may occur anywhere a section or transition may occur. Body
386 elements (including sidebars) may not contain nested sidebars.
388 The directive's sole argument is interpreted as the sidebar title,
389 which may be followed by a subtitle option (see below); the next line
390 must be blank. All subsequent lines make up the sidebar body,
391 interpreted as body elements. For example::
393 .. sidebar:: Optional Sidebar Title
394 :subtitle: Optional Sidebar Subtitle
396 Subsequent indented lines comprise
397 the body of the sidebar, and are
398 interpreted as body elements.
400 The following options are recognized:
403 The sidebar's subtitle.
405 and the common options `:class:`_ and `:name:`_.
411 .. admonition:: Deprecated
413 The "line-block" directive is deprecated. Use the `line block
416 .. _line block syntax: restructuredtext.html#line-blocks
418 :Directive Type: "line-block"
419 :Doctree Element: line_block_
420 :Directive Arguments: None.
421 :Directive Options: `:class:`_, `:name:`_
422 :Directive Content: Becomes the body of the line block.
424 The "line-block" directive constructs an element where line breaks and
425 initial indentation is significant and inline markup is supported. It
426 is equivalent to a `parsed literal block`_ with different rendering:
427 typically in an ordinary serif typeface instead of a
428 typewriter/monospaced face, and not automatically indented. (Have the
429 line-block directive begin a block quote to get an indented line
430 block.) Line blocks are useful for address blocks and verse (poetry,
431 song lyrics), where the structure of lines is significant. For
432 example, here's a classic::
434 "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by
435 Ewan McTeagle (for Lassie O'Shea):
439 Lend us a couple of bob till Thursday.
440 I'm absolutely skint.
441 But I'm expecting a postal order and I can pay you back
452 :Directive Type: "parsed-literal"
453 :Doctree Element: literal_block_
454 :Directive Arguments: None.
455 :Directive Options: `:class:`_, `:name:`_
456 :Directive Content: Becomes the body of the literal block.
458 Unlike an ordinary literal block, the "parsed-literal" directive
459 constructs a literal block where the text is parsed for inline markup.
460 It is equivalent to a `line block`_ with different rendering:
461 typically in a typewriter/monospaced typeface, like an ordinary
462 literal block. Parsed literal blocks are useful for adding hyperlinks
465 However, care must be taken with the text, because inline markup is
466 recognized and there is no protection from parsing. Backslash-escapes
467 may be necessary to prevent unintended parsing. And because the
468 markup characters are removed by the parser, care must also be taken
469 with vertical alignment. Parsed "ASCII art" is tricky, and extra
470 whitespace may be necessary.
472 For example, all the element names in this content model are links::
476 ( (title_, subtitle_?)?,
478 (docinfo_, transition_?)?,
479 `%structure.model;`_ )
484 :Directive Type: "code"
485 :Doctree Element: literal_block_, `inline elements`_
486 :Directive Arguments: One, optional (formal language).
487 :Directive Options: name, class, number-lines.
488 :Directive Content: Becomes the body of the literal block.
489 :Configuration Setting: syntax_highlight_.
491 (New in Docutils 0.9)
493 The "code" directive constructs a literal block. If the code language is
494 specified, the content is parsed by the Pygments_ syntax highlighter and
495 tokens are stored in nested `inline elements`_ with class arguments
496 according to their syntactic category. The actual highlighting requires
497 a style-sheet (e.g. one `generated by Pygments`__, see the
498 `sandbox/stylesheets`__ for examples).
500 The parsing can be turned off with the syntax_highlight_ configuration
501 setting and command line option or by specifying the language as `:class:`_
502 option instead of directive argument. This also avoids warnings
503 when Pygments_ is not installed or the language is not in the
504 `supported languages and markup formats`_.
506 For inline code, use the `"code" role`_.
508 __ http://pygments.org/docs/cmdline/#generating-styles
509 __ http://docutils.sourceforge.net/sandbox/stylesheets/
510 .. _Pygments: http://pygments.org/
511 .. _syntax_highlight: ../../user/config.html#syntax-highlight
512 .. _supported languages and markup formats: http://pygments.org/languages/
513 .. _"code" role: roles.html#code
516 The following options are recognized:
518 ``number-lines`` : [start line number]
519 Precede every line with a line number.
520 The optional argument is the number of the first line (defaut 1).
522 and the common options `:class:`_ and `:name:`_.
525 The content of the following directive ::
533 is parsed and marked up as Python source code.
539 :Directive Type: "math"
540 :Doctree Element: math_block_
541 :Directive Arguments: None.
542 :Directive Options: `:class:`_, `:name:`_
543 :Directive Content: Becomes the body of the math block.
544 (Content blocks separated by a blank line are put in
545 adjacent math blocks.)
546 :Configuration Setting: math_output_
548 (New in Docutils 0.8)
550 The "math" directive inserts blocks with mathematical content
551 (display formulas, equations) into the document. The input format is
552 *LaTeX math syntax*\ [#math-syntax]_ with support for Unicode
553 symbols, for example::
557 α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)
559 Support is limited to a subset of *LaTeX math* by the conversion
560 required for many output formats. For HTML, the `math_output`_
561 configuration setting (or the corresponding ``--math-output``
562 command line option) select between alternative output formats with
563 different subsets of supported elements. If a writer does not
564 support math typesetting at all, the content is inserted verbatim.
566 .. [#math-syntax] The supported LaTeX commands include AMS extensions
567 (see, e.g., the `Short Math Guide`_).
570 For inline formulas, use the `"math" role`_.
572 .. _Short Math Guide: ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf
573 .. _"math" role: roles.html#math
574 .. _math_output: ../../user/config.html#math-output
579 :Directive Type: "rubric"
580 :Doctree Element: rubric_
581 :Directive Arguments: One, required (rubric text).
582 :Directive Options: `:class:`_, `:name:`_
583 :Directive Content: None.
587 rubric n. 1. a title, heading, or the like, in a manuscript,
588 book, statute, etc., written or printed in red or otherwise
589 distinguished from the rest of the text. ...
591 -- Random House Webster's College Dictionary, 1991
593 The "rubric" directive inserts a "rubric" element into the document
594 tree. A rubric is like an informal heading that doesn't correspond to
595 the document's structure.
601 :Directive Type: "epigraph"
602 :Doctree Element: block_quote_
603 :Directive Arguments: None.
604 :Directive Options: None.
605 :Directive Content: Interpreted as the body of the block quote.
607 An epigraph is an apposite (suitable, apt, or pertinent) short
608 inscription, often a quotation or poem, at the beginning of a document
611 The "epigraph" directive produces an "epigraph"-class block quote.
612 For example, this input::
616 No matter where you go, there you are.
620 becomes this document tree fragment::
622 <block_quote classes="epigraph">
624 No matter where you go, there you are.
632 :Directive Type: "highlights"
633 :Doctree Element: block_quote_
634 :Directive Arguments: None.
635 :Directive Options: None.
636 :Directive Content: Interpreted as the body of the block quote.
638 Highlights summarize the main points of a document or section, often
639 consisting of a list.
641 The "highlights" directive produces a "highlights"-class block quote.
642 See Epigraph_ above for an analogous example.
648 :Directive Type: "pull-quote"
649 :Doctree Element: block_quote_
650 :Directive Arguments: None.
651 :Directive Options: None.
652 :Directive Content: Interpreted as the body of the block quote.
654 A pull-quote is a small selection of text "pulled out and quoted",
655 typically in a larger typeface. Pull-quotes are used to attract
656 attention, especially in long articles.
658 The "pull-quote" directive produces a "pull-quote"-class block quote.
659 See Epigraph_ above for an analogous example.
665 :Directive Type: "compound"
666 :Doctree Element: compound_
667 :Directive Arguments: None.
668 :Directive Options: `:class:`_, `:name:`_
669 :Directive Content: Interpreted as body elements.
671 (New in Docutils 0.3.6)
673 The "compound" directive is used to create a compound paragraph, which
674 is a single logical paragraph containing multiple physical body
675 elements such as simple paragraphs, literal blocks, tables, lists,
676 etc., instead of directly containing text and inline elements. For
681 The 'rm' command is very dangerous. If you are logged
682 in as root and enter ::
687 you will erase the entire contents of your file system.
689 In the example above, a literal block is "embedded" within a sentence
690 that begins in one physical paragraph and ends in another.
694 The "compound" directive is *not* a generic block-level container
695 like HTML's ``<div>`` element. Do not use it only to group a
696 sequence of elements, or you may get unexpected results.
698 If you need a generic block-level container, please use the
699 container_ directive, described below.
701 Compound paragraphs are typically rendered as multiple distinct text
702 blocks, with the possibility of variations to emphasize their logical
705 * If paragraphs are rendered with a first-line indent, only the first
706 physical paragraph of a compound paragraph should have that indent
707 -- second and further physical paragraphs should omit the indents;
708 * vertical spacing between physical elements may be reduced;
715 :Directive Type: "container"
716 :Doctree Element: `container <container element_>`__
717 :Directive Arguments: One or more, optional (class names).
718 :Directive Options: `:name:`_
719 :Directive Content: Interpreted as body elements.
721 (New in Docutils 0.3.10)
723 The "container" directive surrounds its contents (arbitrary body
724 elements) with a generic block-level "container" element. Combined
725 with the optional "classes_" attribute argument(s), this is an
726 extension mechanism for users & applications. For example::
728 .. container:: custom
730 This paragraph might be rendered in a custom way.
732 Parsing the above results in the following pseudo-XML::
734 <container classes="custom">
736 This paragraph might be rendered in a custom way.
738 The "container" directive is the equivalent of HTML's ``<div>``
739 element. It may be used to group a sequence of elements for user- or
740 application-specific purposes.
748 Formal tables need more structure than the reStructuredText syntax
749 supplies. Tables may be given titles with the table_ directive.
750 Sometimes reStructuredText tables are inconvenient to write, or table
751 data in a standard format is readily available. The csv-table_
752 directive supports CSV data.
758 :Directive Type: "table"
759 :Doctree Element: table_
760 :Directive Arguments: One, optional (table title).
761 :Directive Options: Possible (see below).
762 :Directive Content: A normal reStructuredText table.
764 (New in Docutils 0.3.1)
766 The "table" directive is used to associate a
767 title with a table or specify options, e.g.::
769 .. table:: Truth table for "not"
779 The following options are recognized:
781 ``align`` : "left", "center", or "right"
782 The horizontal alignment of the table.
783 (New in Docutils 0.13)
785 ``widths`` : "auto", "grid" or a list of integers
786 A comma- or space-separated list of column widths.
787 The default is the width of the input columns (in characters).
789 The special values "auto" or "grid" may be used by writers to decide
790 whether to delegate the determination of column widths to the backend
791 (LaTeX, the HTML browser, ...).
792 See also the `table_style`_ configuration option.
794 ``width`` : `length`_ or `percentage`_ of the current line width
795 Forces the width of the table to the specified length or percentage
796 of the line width. If omitted, the renderer determines the width
797 of the table based on its contents.
799 and the common options `:class:`_ and `:name:`_.
801 .. _table_style: ../../user/config.html#table-style-html4css1-writer
808 :Directive Type: "csv-table"
809 :Doctree Element: table_
810 :Directive Arguments: One, optional (table title).
811 :Directive Options: Possible (see below).
812 :Directive Content: A CSV (comma-separated values) table.
816 The "csv-table" directive's ":file:" and ":url:" options represent
817 a potential security holes. They can be disabled with the
818 "file_insertion_enabled_" runtime setting.
820 (New in Docutils 0.3.4)
822 The "csv-table" directive is used to create a table from CSV
823 (comma-separated values) data. CSV is a common data format generated
824 by spreadsheet applications and commercial databases. The data may be
825 internal (an integral part of the document) or external (a separate
830 .. csv-table:: Frozen Delights!
831 :header: "Treat", "Quantity", "Description"
834 "Albatross", 2.99, "On a stick!"
835 "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
836 crunchy, now would it?"
837 "Gannet Ripple", 1.99, "On a stick!"
839 Block markup and inline markup within cells is supported. Line ends
840 are recognized within cells.
844 * There is no support for checking that the number of columns in each
845 row is the same. However, this directive supports CSV generators
846 that do not insert "empty" entries at the end of short rows, by
847 automatically adding empty entries.
849 .. Add "strict" option to verify input?
851 .. [#whitespace-delim] Whitespace delimiters are supported only for external
854 .. [#ASCII-char] With Python 2, the valuess for the ``delimiter``,
855 ``quote``, and ``escape`` options must be ASCII characters. (The csv
856 module does not support Unicode and all non-ASCII characters are
857 encoded as multi-byte utf-8 string). This limitation does not exist
860 The following options are recognized:
862 ``widths`` : integer [, integer...] or "auto"
863 A comma- or space-separated list of relative column widths. The
864 default is equal-width columns (100%/#columns).
866 The special value "auto" may be used by writers to decide
867 whether to delegate the determination of column widths to the backend
868 (LaTeX, the HTML browser, ...).
870 ``width`` : `length`_ or `percentage`_ of the current line width
871 Forces the width of the table to the specified length or percentage
872 of the line width. If omitted, the renderer determines the width
873 of the table based on its contents.
875 ``header-rows`` : integer
876 The number of rows of CSV data to use in the table header.
879 ``stub-columns`` : integer
880 The number of table columns to use as stubs (row titles, on the
881 left). Defaults to 0.
883 ``header`` : CSV data
884 Supplemental data for the table header, added independently of and
885 before any ``header-rows`` from the main CSV data. Must use the
886 same CSV format as the main CSV data.
888 ``file`` : string (newlines removed)
889 The local filesystem path to a CSV data file.
891 ``url`` : string (whitespace removed)
892 An Internet URL reference to a CSV data file.
894 ``encoding`` : name of text encoding
895 The text encoding of the external CSV data (file or URL).
896 Defaults to the document's encoding (if specified).
898 ``delim`` : char | "tab" | "space" [#whitespace-delim]_
899 A one-character string\ [#ASCII-char]_ used to separate fields.
900 Defaults to ``,`` (comma). May be specified as a Unicode code
901 point; see the unicode_ directive for syntax details.
904 A one-character string\ [#ASCII-char]_ used to quote elements
905 containing the delimiter or which start with the quote
906 character. Defaults to ``"`` (quote). May be specified as a
907 Unicode code point; see the unicode_ directive for syntax
911 Treat whitespace immediately following the delimiter as
912 significant. The default is to ignore such whitespace.
915 A one-character\ [#ASCII-char]_ string used to escape the
916 delimiter or quote characters. May be specified as a Unicode
917 code point; see the unicode_ directive for syntax details. Used
918 when the delimiter is used in an unquoted field, or when quote
919 characters are used within a field. The default is to double-up
920 the character, e.g. "He said, ""Hi!"""
922 .. Add another possible value, "double", to explicitly indicate
925 ``align`` : "left", "center", or "right"
926 The horizontal alignment of the table.
927 (New in Docutils 0.13)
929 and the common options `:class:`_ and `:name:`_.
935 :Directive Type: "list-table"
936 :Doctree Element: table_
937 :Directive Arguments: One, optional (table title).
938 :Directive Options: Possible (see below).
939 :Directive Content: A uniform two-level bullet list.
941 (New in Docutils 0.3.8. This is an initial implementation; `further
942 ideas`__ may be implemented in the future.)
944 __ ../../dev/rst/alternatives.html#list-driven-tables
946 The "list-table" directive is used to create a table from data in a
947 uniform two-level bullet list. "Uniform" means that each sublist
948 (second-level list) must contain the same number of list items.
952 .. list-table:: Frozen Delights!
964 - If we took the bones out, it wouldn't be
965 crunchy, now would it?
970 The following options are recognized:
972 ``widths`` : integer [integer...] or "auto"
973 A comma- or space-separated list of relative column widths. The
974 default is equal-width columns (100%/#columns).
976 The special value "auto" may be used by writers to decide
977 whether to delegate the determination of column widths to the backend
978 (LaTeX, the HTML browser, ...).
980 ``width`` : `length`_ or `percentage`_ of the current line width
981 Forces the width of the table to the specified length or percentage
982 of the line width. If omitted, the renderer determines the width
983 of the table based on its contents.
985 ``header-rows`` : integer
986 The number of rows of list data to use in the table header.
989 ``stub-columns`` : integer
990 The number of table columns to use as stubs (row titles, on the
991 left). Defaults to 0.
993 ``align`` : "left", "center", or "right"
994 The horizontal alignment of the table.
995 (New in Docutils 0.13)
997 and the common options `:class:`_ and `:name:`_.
1009 :Directive Type: "contents"
1010 :Doctree Elements: pending_, topic_
1011 :Directive Arguments: One, optional: title.
1012 :Directive Options: Possible.
1013 :Directive Content: None.
1015 The "contents" directive generates a table of contents (TOC) in a
1016 topic_. Topics, and therefore tables of contents, may occur anywhere
1017 a section or transition may occur. Body elements and topics may not
1018 contain tables of contents.
1020 Here's the directive in its simplest form::
1024 Language-dependent boilerplate text will be used for the title. The
1025 English default title text is "Contents".
1027 An explicit title may be specified::
1029 .. contents:: Table of Contents
1031 The title may span lines, although it is not recommended::
1033 .. contents:: Here's a very long Table of
1036 Options may be specified for the directive, using a field list::
1038 .. contents:: Table of Contents
1041 If the default title is to be used, the options field list may begin
1042 on the same line as the directive marker::
1044 .. contents:: :depth: 2
1046 The following options are recognized:
1049 The number of section levels that are collected in the table of
1050 contents. The default is unlimited depth.
1052 ``local`` : flag (empty)
1053 Generate a local table of contents. Entries will only include
1054 subsections of the section in which the directive is given. If no
1055 explicit title is given, the table of contents will not be titled.
1057 ``backlinks`` : "entry" or "top" or "none"
1058 Generate links from section headers back to the table of contents
1059 entries, the table of contents itself, or generate no backlinks.
1062 Set a `"classes"`_ attribute value on the topic element. See the
1063 class_ directive below.
1067 .. _section-numbering:
1069 Automatic Section Numbering
1070 ===========================
1072 :Directive Type: "sectnum" or "section-numbering" (synonyms)
1073 :Doctree Elements: pending_, generated_
1074 :Directive Arguments: None.
1075 :Directive Options: Possible.
1076 :Directive Content: None.
1077 :Configuration Setting: sectnum_xform_
1079 The "sectnum" (or "section-numbering") directive automatically numbers
1080 sections and subsections in a document (if not disabled by the
1081 ``--no-section-numbering`` command line option or the `sectnum_xform`_
1082 configuration setting).
1084 Section numbers are of the "multiple enumeration" form, where each
1085 level has a number, separated by periods. For example, the title of section
1086 1, subsection 2, subsubsection 3 would have "1.2.3" prefixed.
1088 The "sectnum" directive does its work in two passes: the initial parse
1089 and a transform. During the initial parse, a "pending" element is
1090 generated which acts as a placeholder, storing any options internally.
1091 At a later stage in the processing, the "pending" element triggers a
1092 transform, which adds section numbers to titles. Section numbers are
1093 enclosed in a "generated" element, and titles have their "auto"
1094 attribute set to "1".
1096 The following options are recognized:
1099 The number of section levels that are numbered by this directive.
1100 The default is unlimited depth.
1103 An arbitrary string that is prefixed to the automatically
1104 generated section numbers. It may be something like "3.2.", which
1105 will produce "3.2.1", "3.2.2", "3.2.2.1", and so on. Note that
1106 any separating punctuation (in the example, a period, ".") must be
1107 explicitly provided. The default is no prefix.
1110 An arbitrary string that is appended to the automatically
1111 generated section numbers. The default is no suffix.
1114 The value that will be used for the first section number.
1115 Combined with ``prefix``, this may be used to force the right
1116 numbering for a document split over several source files. The
1119 .. _sectnum_xform: ../../user/config.html#sectnum-xform
1125 Document Header & Footer
1126 ========================
1128 :Directive Types: "header" and "footer"
1129 :Doctree Elements: decoration_, header, footer
1130 :Directive Arguments: None.
1131 :Directive Options: None.
1132 :Directive Content: Interpreted as body elements.
1134 (New in Docutils 0.3.8)
1136 The "header" and "footer" directives create document decorations,
1137 useful for page navigation, notes, time/datestamp, etc. For example::
1139 .. header:: This space for rent.
1141 This will add a paragraph to the document header, which will appear at
1142 the top of the generated web page or at the top of every printed page.
1144 These directives may be used multiple times, cumulatively. There is
1145 currently support for only one header and footer.
1149 While it is possible to use the "header" and "footer" directives to
1150 create navigational elements for web pages, you should be aware
1151 that Docutils is meant to be used for *document* processing, and
1152 that a navigation bar is not typically part of a document.
1154 Thus, you may soon find Docutils' abilities to be insufficient for
1155 these purposes. At that time, you should consider using a
1156 documentation generator like Sphinx_ rather than the "header" and
1157 "footer" directives.
1159 .. _Sphinx: http://sphinx-doc.org/
1161 In addition to the use of these directives to populate header and
1162 footer content, content may also be added automatically by the
1163 processing system. For example, if certain runtime settings are
1164 enabled, the document footer is populated with processing information
1165 such as a datestamp, a link to `the Docutils website`_, etc.
1167 .. _the Docutils website: http://docutils.sourceforge.net
1179 :Directive Type: "target-notes"
1180 :Doctree Elements: pending_, footnote_, footnote_reference_
1181 :Directive Arguments: None.
1182 :Directive Options: `:class:`_, `:name:`_
1183 :Directive Options: Possible.
1184 :Directive Content: None.
1186 The "target-notes" directive creates a footnote for each external
1187 target in the text, and corresponding footnote references after each
1188 reference. For every explicit target (of the form, ``.. _target name:
1189 URL``) in the text, a footnote will be generated containing the
1190 visible URL as content.
1196 **NOT IMPLEMENTED YET**
1198 :Directive Type: "footnotes"
1199 :Doctree Elements: pending_, topic_
1200 :Directive Arguments: None?
1201 :Directive Options: Possible?
1202 :Directive Content: None.
1210 **NOT IMPLEMENTED YET**
1212 :Directive Type: "citations"
1213 :Doctree Elements: pending_, topic_
1214 :Directive Arguments: None?
1215 :Directive Options: Possible?
1216 :Directive Content: None.
1228 :Directive Type: "meta"
1229 :Doctree Element: meta (non-standard)
1230 :Directive Arguments: None.
1231 :Directive Options: None.
1232 :Directive Content: Must contain a flat field list.
1234 The "meta" directive is used to specify HTML metadata stored in HTML
1235 META tags. "Metadata" is data about data, in this case data about web
1236 pages. Metadata is used to describe and classify web pages in the
1237 World Wide Web, in a form that is easy for search engines to extract
1240 Within the directive block, a flat field list provides the syntax for
1241 metadata. The field name becomes the contents of the "name" attribute
1242 of the META tag, and the field body (interpreted as a single string
1243 without inline markup) becomes the contents of the "content"
1244 attribute. For example::
1247 :description: The reStructuredText plaintext markup language
1248 :keywords: plaintext, markup language
1250 This would be converted to the following HTML::
1252 <meta name="description"
1253 content="The reStructuredText plaintext markup language">
1254 <meta name="keywords" content="plaintext, markup language">
1256 Support for other META attributes ("http-equiv", "scheme", "lang",
1257 "dir") are provided through field arguments, which must be of the form
1261 :description lang=en: An amusing story
1262 :description lang=fr: Une histoire amusante
1264 And their HTML equivalents::
1266 <meta name="description" lang="en" content="An amusing story">
1267 <meta name="description" lang="fr" content="Une histoire amusante">
1269 Some META tags use an "http-equiv" attribute instead of the "name"
1270 attribute. To specify "http-equiv" META tags, simply omit the name::
1273 :http-equiv=Content-Type: text/html; charset=ISO-8859-1
1277 <meta http-equiv="Content-Type"
1278 content="text/html; charset=ISO-8859-1">
1284 **NOT IMPLEMENTED YET**
1286 Non-standard element: imagemap.
1289 -----------------------------------------
1290 Directives for Substitution Definitions
1291 -----------------------------------------
1293 The directives in this section may only be used in `substitution
1294 definitions`_. They may not be used directly, in standalone context.
1295 The `image`_ directive may be used both in substitution definitions
1296 and in the standalone context.
1298 .. _substitution definitions:
1299 .. _substitution definition: restructuredtext.html#substitution-definitions
1306 :Directive Type: "replace"
1307 :Doctree Element: Text & `inline elements`_
1308 :Directive Arguments: None.
1309 :Directive Options: None.
1310 :Directive Content: A single paragraph; may contain inline markup.
1312 The "replace" directive is used to indicate replacement text for a
1313 substitution reference. It may be used within `substitution
1314 definitions`_ only. For example, this directive can be used to expand
1317 .. |reST| replace:: reStructuredText
1319 Yes, |reST| is a long word, so I can't blame anyone for wanting to
1322 As reStructuredText doesn't support nested inline markup, the only way
1323 to create a reference with styled text is to use substitutions with
1324 the "replace" directive::
1326 I recommend you try |Python|_.
1328 .. |Python| replace:: Python, *the* best language around
1329 .. _Python: http://www.python.org/
1334 Unicode Character Codes
1335 =======================
1337 :Directive Type: "unicode"
1338 :Doctree Element: Text
1339 :Directive Arguments: One or more, required (Unicode character codes,
1340 optional text, and comments).
1341 :Directive Options: Possible.
1342 :Directive Content: None.
1344 The "unicode" directive converts Unicode character codes (numerical
1345 values) to characters, and may be used in `substitution definitions`_
1348 The arguments, separated by spaces, can be:
1350 * **character codes** as
1352 - decimal numbers or
1354 - hexadecimal numbers, prefixed by ``0x``, ``x``, ``\x``, ``U+``,
1355 ``u``, or ``\u`` or as XML-style hexadecimal character entities,
1358 * **text**, which is used as-is.
1360 Text following " .. " is a comment and is ignored. The spaces between
1361 the arguments are ignored and thus do not appear in the output.
1362 Hexadecimal codes are case-insensitive.
1364 For example, the following text::
1366 Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|
1367 all rights reserved.
1369 .. |copy| unicode:: 0xA9 .. copyright sign
1370 .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
1371 .. with trademark sign
1372 .. |---| unicode:: U+02014 .. em dash
1377 Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|
1378 all rights reserved.
1380 .. |copy| unicode:: 0xA9 .. copyright sign
1381 .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
1382 .. with trademark sign
1383 .. |---| unicode:: U+02014 .. em dash
1386 The following options are recognized:
1389 Whitespace to the left of the substitution reference is removed.
1392 Whitespace to the right of the substitution reference is removed.
1395 Equivalent to ``ltrim`` plus ``rtrim``; whitespace on both sides
1396 of the substitution reference is removed.
1402 :Directive Type: "date"
1403 :Doctree Element: Text
1404 :Directive Arguments: One, optional (date format).
1405 :Directive Options: None.
1406 :Directive Content: None.
1408 The "date" directive generates the current local date and inserts it
1409 into the document as text. This directive may be used in substitution
1412 The optional directive content is interpreted as the desired date
1413 format, using the same codes as Python's time.strftime function. The
1414 default format is "%Y-%m-%d" (ISO 8601 date), but time fields can also
1418 .. |time| date:: %H:%M
1420 Today's date is |date|.
1422 This document was generated on |date| at |time|.
1431 Including an External Document Fragment
1432 =======================================
1434 :Directive Type: "include"
1435 :Doctree Elements: Depend on data being included
1436 (literal_block_ with ``code`` or ``literal`` option).
1437 :Directive Arguments: One, required (path to the file to include).
1438 :Directive Options: Possible.
1439 :Directive Content: None.
1440 :Configuration Setting: file_insertion_enabled_
1444 The "include" directive represents a potential security hole. It
1445 can be disabled with the "file_insertion_enabled_" runtime setting.
1447 .. _file_insertion_enabled: ../../user/config.html#file-insertion-enabled
1449 The "include" directive reads a text file. The directive argument is
1450 the path to the file to be included, relative to the document
1451 containing the directive. Unless the options ``literal`` or ``code``
1452 are given, the file is parsed in the current document's context at the
1453 point of the directive. For example::
1455 This first example will be parsed at the document level, and can
1456 thus contain any construct, including section headers.
1458 .. include:: inclusion.txt
1460 Back in the main document.
1462 This second example will be parsed in a block quote context.
1463 Therefore it may only contain body elements. It may not
1464 contain section headers.
1466 .. include:: inclusion.txt
1468 If an included document fragment contains section structure, the title
1469 adornments must match those of the master document.
1471 Standard data files intended for inclusion in reStructuredText
1472 documents are distributed with the Docutils source code, located in
1473 the "docutils" package in the ``docutils/parsers/rst/include``
1474 directory. To access these files, use the special syntax for standard
1475 "include" data files, angle brackets around the file name::
1477 .. include:: <isonum.txt>
1479 The current set of standard "include" data files consists of sets of
1480 substitution definitions. See `reStructuredText Standard Definition
1481 Files`__ for details.
1485 The following options are recognized:
1487 ``start-line`` : integer
1488 Only the content starting from this line will be included.
1489 (As usual in Python, the first line has index 0 and negative values
1490 count from the end.)
1492 ``end-line`` : integer
1493 Only the content up to (but excluding) this line will be included.
1495 ``start-after`` : text to find in the external data file
1496 Only the content after the first occurrence of the specified text
1499 ``end-before`` : text to find in the external data file
1500 Only the content before the first occurrence of the specified text
1501 (but after any ``after`` text) will be included.
1503 ``literal`` : flag (empty)
1504 The entire included text is inserted into the document as a single
1507 ``code`` : formal language (optional)
1508 The argument and the content of the included file are passed to
1509 the code_ directive (useful for program listings).
1510 (New in Docutils 0.9)
1512 ``number-lines`` : [start line number]
1513 Precede every code line with a line number.
1514 The optional argument is the number of the first line (defaut 1).
1515 Works only with ``code`` or ``literal``.
1516 (New in Docutils 0.9)
1518 ``encoding`` : name of text encoding
1519 The text encoding of the external data file. Defaults to the
1520 document's input_encoding_.
1522 .. _input_encoding: ../../user/config.html#input-encoding
1524 ``tab-width`` : integer
1525 Number of spaces for hard tab expansion.
1526 A negative value prevents expansion of hard tabs. Defaults to the
1527 tab_width_ configuration setting.
1529 .. _tab_width: ../../user/config.html#tab-width
1532 With ``code`` or ``literal`` the common options `:class:`_ and
1533 `:name:`_ are recognized as well.
1535 Combining ``start/end-line`` and ``start-after/end-before`` is possible. The
1536 text markers will be searched in the specified lines (further limiting the
1541 Raw Data Pass-Through
1542 =====================
1544 :Directive Type: "raw"
1545 :Doctree Element: raw_
1546 :Directive Arguments: One or more, required (output format types).
1547 :Directive Options: Possible.
1548 :Directive Content: Stored verbatim, uninterpreted. None (empty) if a
1549 "file" or "url" option given.
1550 :Configuration Setting: raw_enabled_
1554 The "raw" directive represents a potential security hole. It can
1555 be disabled with the "raw_enabled_" or "file_insertion_enabled_"
1558 .. _raw_enabled: ../../user/config.html#raw-enabled
1562 The "raw" directive is a stop-gap measure allowing the author to
1563 bypass reStructuredText's markup. It is a "power-user" feature
1564 that should not be overused or abused. The use of "raw" ties
1565 documents to specific output formats and makes them less portable.
1567 If you often need to use the "raw" directive or a "raw"-derived
1568 interpreted text role, that is a sign either of overuse/abuse or
1569 that functionality may be missing from reStructuredText. Please
1570 describe your situation in a message to the Docutils-users_ mailing
1573 .. _Docutils-users: ../../user/mailing-lists.html#docutils-users
1575 The "raw" directive indicates non-reStructuredText data that is to be
1576 passed untouched to the Writer. The names of the output formats are
1577 given in the directive arguments. The interpretation of the raw data
1578 is up to the Writer. A Writer may ignore any raw output not matching
1581 For example, the following input would be passed untouched by an HTML
1586 <hr width=50 size=10>
1588 A LaTeX Writer could insert the following raw content into its
1593 \setlength{\parindent}{0pt}
1595 Raw data can also be read from an external file, specified in a
1596 directive option. In this case, the content block must be empty. For
1600 :file: inclusion.html
1602 Inline equivalents of the "raw" directive can be defined via
1603 `custom interpreted text roles`_ derived from the `"raw" role`_.
1605 The following options are recognized:
1607 ``file`` : string (newlines removed)
1608 The local filesystem path of a raw data file to be included.
1610 ``url`` : string (whitespace removed)
1611 An Internet URL reference to a raw data file to be included.
1613 ``encoding`` : name of text encoding
1614 The text encoding of the external raw data (file or URL).
1615 Defaults to the document's encoding (if specified).
1617 .. _"raw" role: roles.html#raw
1625 :Directive Type: "class"
1626 :Doctree Element: pending_
1627 :Directive Arguments: One or more, required (class names / attribute
1629 :Directive Options: None.
1630 :Directive Content: Optional. If present, it is interpreted as body
1633 The "class" directive sets the `"classes"`_ attribute value on its content
1634 or on the first immediately following [#]_ non-comment element [#]_.
1635 The directive argument consists of one or more space-separated class
1636 names. The names are transformed to conform to the regular expression
1637 ``[a-z](-?[a-z0-9]+)*`` (see `Identifier Normalization`_ below).
1643 This is a "special" paragraph.
1645 .. class:: exceptional remarkable
1647 An Exceptional Section
1648 ======================
1650 This is an ordinary paragraph.
1658 The text above is parsed and transformed into this doctree fragment::
1660 <paragraph classes="special">
1661 This is a "special" paragraph.
1662 <section classes="exceptional remarkable">
1664 An Exceptional Section
1666 This is an ordinary paragraph.
1667 <paragraph classes="multiple">
1669 <paragraph classes="multiple">
1673 .. [#] This is also true, if the class directive is "nested" at the end of
1674 an indented text block, for example::
1676 .. note:: the class values set in this directive-block do not apply to
1677 the note but the next paragraph.
1681 This is a paragraph with class value "special".
1683 This allows the "classification" of individual list items (except the
1684 first, as a preceding class directive applies to the list as a whole)::
1688 .. class:: classy item
1690 * second item, with class argument
1692 .. [#] To set a "classes" attribute value on a block quote, the
1693 "class" directive must be followed by an empty comment::
1695 .. class:: highlights
1700 Without the empty comment, the indented text would be interpreted as the
1701 "class" directive's content, and the classes would be applied to each
1702 element (paragraph, in this case) individually, instead of to the block
1706 Identifier Normalization
1707 ~~~~~~~~~~~~~~~~~~~~~~~~
1709 Docutils `class names`_ and `identifier keys`_ are normalized to conform
1710 to the regular expression "``[a-z](-?[a-z0-9]+)*``" by converting
1712 * alphabetic characters to lowercase,
1713 * accented characters to the base character,
1714 * non-alphanumeric characters to hyphens,
1715 * consecutive hyphens into one hyphen
1719 * leading hyphens and number characters, and
1722 For example ``"Rot.Gelb&Grün:+2008"`` becomes ``"rot-gelb-grun-2008"`` and
1723 ``"1000_Steps!"`` becomes ``"steps"``.
1725 .. topic:: Rationale:
1727 Identifier keys must be valid in all supported output formats.
1729 For HTML 4.1 + CSS1 compatibility, identifiers should have no
1730 underscores, colons, or periods. Hyphens may be used.
1732 - The `HTML 4.01 spec`_ defines identifiers based on SGML tokens:
1734 ID and NAME tokens must begin with a letter ([A-Za-z]) and
1735 may be followed by any number of letters, digits ([0-9]),
1736 hyphens ("-"), underscores ("_"), colons (":"), and periods
1739 -- http://www.w3.org/TR/html401/types.html#type-name
1741 - The `CSS1 spec`_ defines identifiers based on the "name" token
1742 ("flex" tokenizer notation below; "latin1" and "escape" 8-bit
1743 characters have been replaced with XML entities)::
1745 unicode \\[0-9a-f]{1,4}
1746 latin1 [¡-ÿ]
1747 escape {unicode}|\\[ -~¡-ÿ]
1748 nmchar [-A-Za-z0-9]|{latin1}|{escape}
1751 The CSS1 rule requires underscores ("_"), colons (":"), and
1752 periods (".") to be escaped [#]_,
1753 therefore `"classes"`_ and `"ids"`_ attributes should not
1754 contain these characters. Combined with HTML4.1 requirements (the
1755 first character must be a letter; no "unicode", "latin1", or
1756 "escape" characters), this results in the regular expression
1757 ``[A-Za-z][-A-Za-z0-9]*``. Docutils adds a normalization by
1758 downcasing and merge of consecutive hyphens.
1760 .. [#] CSS identifiers may use underscores ("_") directly in
1761 `CSS Level 1`__, `CSS2.1`__, CSS2.2__, and CSS3__.
1763 __ https://www.w3.org/TR/CSS21/syndata.html#value-def-identifier
1764 __ https://www.w3.org/TR/CSS/#css-level-1
1765 __ https://www.w3.org/TR/CSS22/syndata.html
1766 __ https://www.w3.org/TR/css-syntax-3/#typedef-ident-token
1768 .. _HTML 4.01 spec: http://www.w3.org/TR/html401/
1769 .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1
1773 Custom Interpreted Text Roles
1774 =============================
1776 :Directive Type: "role"
1777 :Doctree Element: None; affects subsequent parsing.
1778 :Directive Arguments: Two; one required (new role name), one optional
1779 (base role name, in parentheses).
1780 :Directive Options: Possible (depends on base role).
1781 :Directive Content: depends on base role.
1783 (New in Docutils 0.3.2)
1785 The "role" directive dynamically creates a custom interpreted text
1786 role and registers it with the parser. This means that after
1787 declaring a role like this::
1791 the document may use the new "custom" role::
1793 An example of using :custom:`interpreted text`
1795 This will be parsed into the following document tree fragment::
1799 <inline classes="custom">
1802 The role must be declared in a document before it can be used.
1804 The new role may be based on an existing role, specified as a second
1805 argument in parentheses (whitespace optional)::
1807 .. role:: custom(emphasis)
1811 The parsed result is as follows::
1814 <emphasis classes="custom">
1817 A special case is the `"raw" role`_: derived roles enable
1818 inline `raw data pass-through`_, e.g.::
1820 .. role:: raw-role(raw)
1823 :raw-role:`raw text`
1825 If no base role is explicitly specified, a generic custom role is
1826 automatically used. Subsequent interpreted text will produce an
1827 "inline" element with a `"classes"`_ attribute, as in the first example
1830 With most roles, the ":class:" option can be used to set a "classes"
1831 attribute that is different from the role name. For example::
1836 :custom:`interpreted text`
1838 This is the parsed result::
1841 <inline classes="special">
1846 The following option is recognized by the "role" directive for most
1850 Set the `"classes"`_ attribute value on the element produced
1851 (``inline``, or element associated with a base class) when the
1852 custom interpreted text role is used. If no directive options are
1853 specified, a "class" option with the directive argument (role
1854 name) as the value is implied. See the class_ directive above.
1856 Specific base roles may support other options and/or directive
1857 content. See the `reStructuredText Interpreted Text Roles`_ document
1860 .. _reStructuredText Interpreted Text Roles: roles.html
1865 Setting the Default Interpreted Text Role
1866 =========================================
1868 :Directive Type: "default-role"
1869 :Doctree Element: None; affects subsequent parsing.
1870 :Directive Arguments: One, optional (new default role name).
1871 :Directive Options: None.
1872 :Directive Content: None.
1874 (New in Docutils 0.3.10)
1876 The "default-role" directive sets the default interpreted text role,
1877 the role that is used for interpreted text without an explicit role.
1878 For example, after setting the default role like this::
1880 .. default-role:: subscript
1882 any subsequent use of implicit-role interpreted text in the document
1883 will use the "subscript" role::
1885 An example of a `default` role.
1887 This will be parsed into the following document tree fragment::
1895 Custom roles may be used (see the "role_" directive above), but it
1896 must have been declared in a document before it can be set as the
1897 default role. See the `reStructuredText Interpreted Text Roles`_
1898 document for details of built-in roles.
1900 The directive may be used without an argument to restore the initial
1901 default interpreted text role, which is application-dependent. The
1902 initial default interpreted text role of the standard reStructuredText
1903 parser is "title-reference".
1906 Metadata Document Title
1907 =======================
1909 :Directive Type: "title"
1910 :Doctree Element: None.
1911 :Directive Arguments: One, required (the title text).
1912 :Directive Options: None.
1913 :Directive Content: None.
1915 The "title" directive specifies the document title as metadata, which
1916 does not become part of the document body. It overrides a
1917 document-supplied title. For example, in HTML output the metadata
1918 document title appears in the title bar of the browser window.
1921 Restructuredtext-Test-Directive
1922 ===============================
1924 :Directive Type: "restructuredtext-test-directive"
1925 :Doctree Element: system_warning
1926 :Directive Arguments: None.
1927 :Directive Options: None.
1928 :Directive Content: Interpreted as a literal block.
1930 This directive is provided for test purposes only. (Nobody is
1931 expected to type in a name *that* long!) It is converted into a
1932 level-1 (info) system message showing the directive data, possibly
1933 followed by a literal block containing the rest of the directive
1940 Most of the directives that generate doctree elements support the following
1946 Set a `"classes"`_ attribute value on the doctree element generated by
1947 the directive. See also the class_ directive.
1950 Add `text` to the `"names"`_ attribute of the doctree element generated
1951 by the directive. This allows `hyperlink references`_ to the element
1952 using `text` as `reference name`_.
1954 Specifying the `name` option of a directive, e.g., ::
1959 is a concise syntax alternative to preceding it with a `hyperlink
1966 New in Docutils 0.8.
1969 .. _reference name: restructuredtext.html#reference-names
1970 .. _hyperlink target: restructuredtext.html#hyperlink-targets
1971 .. _hyperlink references: restructuredtext.html#hyperlink-references
1972 .. _class names: ../doctree.html#classnames-type
1973 .. _"classes": ../doctree.html#classes
1974 .. _identifier keys: ../doctree.html#ids-type
1975 .. _"ids": ../doctree.html#ids
1976 .. _"names": ../doctree.html#names
1977 .. _admonition: ../doctree.html#admonition
1978 .. _block_quote: ../doctree.html#block-quote
1979 .. _caption: ../doctree.html#caption
1980 .. _compound: ../doctree.html#compound
1981 .. _container element: ../doctree.html#container
1982 .. _decoration: ../doctree.html#decoration
1983 .. _figure: ../doctree.html#figure
1984 .. _footnote: ../doctree.html#footnote
1985 .. _footnote_reference: ../doctree.html#footnote-reference
1986 .. _generated: ../doctree.html#generated
1987 .. _image: ../doctree.html#image
1988 .. _inline elements: ../doctree.html#inline-elements
1989 .. _literal_block: ../doctree.html#literal-block
1990 .. _legend: ../doctree.html#legend
1991 .. _length: restructuredtext.html#length-units
1992 .. _line_block: ../doctree.html#line-block
1993 .. _math_block: ../doctree.html#math-block
1994 .. _pending: ../doctree.html#pending
1995 .. _percentage: restructuredtext.html#percentage-units
1996 .. _raw: ../doctree.html#raw
1997 .. _rubric: ../doctree.html#rubric
1998 .. _sidebar: ../doctree.html#sidebar
1999 .. _table: ../doctree.html#table
2000 .. _title: ../doctree.html#title
2001 .. _topic: ../doctree.html#topic
2008 indent-tabs-mode: nil
2009 sentence-end-double-space: t