1 =============================
2 reStructuredText Directives
3 =============================
5 :Contact: docutils-develop@lists.sourceforge.net
8 :Copyright: This document has been placed in the public domain.
12 This document describes the directives implemented in the reference
13 reStructuredText parser.
15 Directives have the following syntax::
17 +-------+-------------------------------+
18 | ".. " | directive type "::" directive |
21 +-------------------------------+
23 Directives begin with an explicit markup start (two periods and a
24 space), followed by the directive type and two colons (collectively,
25 the "directive marker"). The directive block begins immediately after
26 the directive marker, and includes all subsequent indented lines. The
27 directive block is divided into arguments, options (a field list), and
28 content (in that order), any of which may appear. See the Directives_
29 section in the `reStructuredText Markup Specification`_ for syntax
32 Descriptions below list "doctree elements" (document tree element
33 names; XML DTD generic identifiers) corresponding to individual
34 directives. For details on the hierarchy of elements, please see `The
35 Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document
36 type definition. For directive implementation details, see `Creating
37 reStructuredText Directives`_.
39 .. _Directives: restructuredtext.html#directives
40 .. _reStructuredText Markup Specification: restructuredtext.html
41 .. _The Docutils Document Tree: ../doctree.html
42 .. _Docutils Generic DTD: ../docutils.dtd
43 .. _Creating reStructuredText Directives:
44 ../../howto/rst-directives.html
64 :Directive Types: "attention", "caution", "danger", "error", "hint",
65 "important", "note", "tip", "warning", "admonition"
66 :Doctree Elements: attention, caution, danger, error, hint, important,
67 note, tip, warning, admonition_, title
68 :Directive Arguments: None.
69 :Directive Options: `:class:`_, `:name:`_
70 :Directive Content: Interpreted as body elements.
72 Admonitions are specially marked "topics" that can appear anywhere an
73 ordinary body element can. They contain arbitrary body elements.
74 Typically, an admonition is rendered as an offset block in a document,
75 sometimes outlined or shaded, with a title matching the admonition
79 Beware killer rabbits!
81 This directive might be rendered something like this::
83 +------------------------+
86 | Beware killer rabbits! |
87 +------------------------+
89 The following admonition directives have been implemented:
101 Any text immediately following the directive indicator (on the same
102 line and/or indented on following lines) is interpreted as a directive
103 block and is parsed for normal body elements. For example, the
104 following "note" admonition directive contains one paragraph and a
105 bullet list consisting of two list items::
107 .. note:: This is a note admonition.
108 This is the second line of the first paragraph.
110 - The note contains all indented body elements
112 - It includes this bullet list.
118 :Directive Type: "admonition"
119 :Doctree Elements: admonition_, title
120 :Directive Arguments: One, required (admonition title)
121 :Directive Options: Possible, see below.
122 :Directive Content: Interpreted as body elements.
124 This is a generic, titled admonition. The title may be anything the
127 The author-supplied title is also used as a `"classes"`_ attribute value
128 after being converted into a valid identifier form (down-cased;
129 non-alphanumeric characters converted to single hyphens; "admonition-"
130 prefixed). For example, this admonition::
132 .. admonition:: And, by the way...
134 You can make up your own admonition too.
136 becomes the following document tree (pseudo-XML)::
138 <document source="test data">
139 <admonition classes="admonition-and-by-the-way">
143 You can make up your own admonition too.
145 The `common options`_ are recognized:
148 Overrides the computed `"classes"`_ attribute value.
151 Add `text` to the `"names"`_ attribute of the admonition element.
158 There are two image directives: "image" and "figure".
164 :Directive Type: "image"
165 :Doctree Element: image_
166 :Directive Arguments: One, required (image URI).
167 :Directive Options: Possible.
168 :Directive Content: None.
170 An "image" is a simple picture::
172 .. image:: picture.png
174 Inline images can be defined with an "image" directive in a `substitution
177 The URI for the image source file is specified in the directive
178 argument. As with hyperlink targets, the image URI may begin on the
179 same line as the explicit markup start and target name, or it may
180 begin in an indented text block immediately following, with no
181 intervening blank lines. If there are multiple lines in the link
182 block, they are stripped of leading and trailing whitespace and joined
185 Optionally, the image link block may contain a flat field list, the
186 _`image options`. For example::
188 .. image:: picture.jpeg
195 The following options are recognized:
198 Alternate text: a short description of the image, displayed by
199 applications that cannot display images, or spoken by applications
200 for visually impaired users.
202 ``height`` : `length`_
203 The desired height of the image.
204 Used to reserve space or scale the image vertically. When the "scale"
205 option is also specified, they are combined. For example, a height of
206 200px and a scale of 50 is equivalent to a height of 100px with no scale.
208 ``width`` : `length`_ or `percentage`_ of the current line width
209 The width of the image.
210 Used to reserve space or scale the image horizontally. As with "height"
211 above, when the "scale" option is also specified, they are combined.
213 .. _length: restructuredtext.html#length-units
214 .. _percentage: restructuredtext.html#percentage-units
216 ``scale`` : integer percentage (the "%" symbol is optional)
217 The uniform scaling factor of the image. The default is "100 %", i.e.
220 If no "height" or "width" options are specified, the `Python Imaging
221 Library`_ (PIL) may be used to determine them, if it is installed and
222 the image file is available.
224 ``align`` : "top", "middle", "bottom", "left", "center", or "right"
225 The alignment of the image, equivalent to the HTML ``<img>`` tag's
226 deprecated "align" attribute or the corresponding "vertical-align" and
227 "text-align" CSS properties.
228 The values "top", "middle", and "bottom"
229 control an image's vertical alignment (relative to the text
230 baseline); they are only useful for inline images (substitutions).
231 The values "left", "center", and "right" control an image's
232 horizontal alignment, allowing the image to float and have the
233 text flow around it. The specific behavior depends upon the
234 browser or rendering software used.
236 ``target`` : text (URI or reference name)
237 Makes the image into a hyperlink reference ("clickable"). The
238 option argument may be a URI (relative or absolute), or a
239 `reference name`_ with underscore suffix (e.g. ```a name`_``).
241 and the common options `:class:`_ and `:name:`_.
243 .. _substitution definition: restructuredtext.html#substitution-definitions
249 :Directive Type: "figure"
250 :Doctree Elements: figure_, image_, caption_, legend_
251 :Directive Arguments: One, required (image URI).
252 :Directive Options: Possible.
253 :Directive Content: Interpreted as the figure caption and an optional
256 A "figure" consists of image_ data (including `image options`_), an optional
257 caption (a single paragraph), and an optional legend (arbitrary body
258 elements). For page-based output media, figures might float to a different
259 position if this helps the page layout.
262 .. figure:: picture.png
264 :alt: map to buried treasure
266 This is the caption of the figure (a simple paragraph).
268 The legend consists of all elements after the caption. In this
269 case, the legend consists of this paragraph and the following
272 +-----------------------+-----------------------+
274 +=======================+=======================+
275 | .. image:: tent.png | Campground |
276 +-----------------------+-----------------------+
277 | .. image:: waves.png | Lake |
278 +-----------------------+-----------------------+
279 | .. image:: peak.png | Mountain |
280 +-----------------------+-----------------------+
282 There must be blank lines before the caption paragraph and before the
283 legend. To specify a legend without a caption, use an empty comment
284 ("..") in place of the caption.
286 The "figure" directive supports all of the options of the "image"
287 directive (see `image options`_ above). These options (except
288 "align") are passed on to the contained image.
290 ``align`` : "left", "center", or "right"
291 The horizontal alignment of the figure, allowing the image to
292 float and have the text flow around it. The specific behavior
293 depends upon the browser or rendering software used.
295 In addition, the following options are recognized:
297 ``figwidth`` : "image", length_, or percentage_ of current line width
298 The width of the figure.
299 Limits the horizontal space used by the figure.
300 A special value of "image" is allowed, in which case the
301 included image's actual width is used (requires the `Python Imaging
302 Library`_). If the image file is not found or the required software is
303 unavailable, this option is ignored.
305 Sets the "width" attribute of the "figure" doctree element.
307 This option does not scale the included image; use the "width"
308 `image`_ option for that. ::
310 +---------------------------+
313 |<------ figwidth --------->|
315 | +---------------------+ |
318 | |<--- width --------->| |
319 | +---------------------+ |
321 |The figure's caption should|
322 |wrap at this width. |
323 +---------------------------+
326 Set a `"classes"`_ attribute value on the figure element. See the
327 class_ directive below.
329 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
339 :Directive Type: "topic"
340 :Doctree Element: topic_
341 :Directive Arguments: 1, required (topic title).
342 :Directive Options: `:class:`_, `:name:`_
343 :Directive Content: Interpreted as the topic body.
345 A topic is like a block quote with a title, or a self-contained
346 section with no subsections. Use the "topic" directive to indicate a
347 self-contained idea that is separate from the flow of the document.
348 Topics may occur anywhere a section or transition may occur. Body
349 elements and topics may not contain nested topics.
351 The directive's sole argument is interpreted as the topic title; the
352 next line must be blank. All subsequent lines make up the topic body,
353 interpreted as body elements. For example::
355 .. topic:: Topic Title
357 Subsequent indented lines comprise
358 the body of the topic, and are
359 interpreted as body elements.
365 :Directive Type: "sidebar"
366 :Doctree Element: sidebar_
367 :Directive Arguments: One, required (sidebar title).
368 :Directive Options: Possible (see below).
369 :Directive Content: Interpreted as the sidebar body.
371 Sidebars are like miniature, parallel documents that occur inside
372 other documents, providing related or reference material. A sidebar
373 is typically offset by a border and "floats" to the side of the page;
374 the document's main text may flow around it. Sidebars can also be
375 likened to super-footnotes; their content is outside of the flow of
376 the document's main text.
378 Sidebars may occur anywhere a section or transition may occur. Body
379 elements (including sidebars) may not contain nested sidebars.
381 The directive's sole argument is interpreted as the sidebar title,
382 which may be followed by a subtitle option (see below); the next line
383 must be blank. All subsequent lines make up the sidebar body,
384 interpreted as body elements. For example::
386 .. sidebar:: Sidebar Title
387 :subtitle: Optional Sidebar Subtitle
389 Subsequent indented lines comprise
390 the body of the sidebar, and are
391 interpreted as body elements.
393 The following options are recognized:
396 The sidebar's subtitle.
398 and the common options `:class:`_ and `:name:`_.
404 .. admonition:: Deprecated
406 The "line-block" directive is deprecated. Use the `line block
409 .. _line block syntax: restructuredtext.html#line-blocks
411 :Directive Type: "line-block"
412 :Doctree Element: line_block_
413 :Directive Arguments: None.
414 :Directive Options: `:class:`_, `:name:`_
415 :Directive Content: Becomes the body of the line block.
417 The "line-block" directive constructs an element where line breaks and
418 initial indentation is significant and inline markup is supported. It
419 is equivalent to a `parsed literal block`_ with different rendering:
420 typically in an ordinary serif typeface instead of a
421 typewriter/monospaced face, and not automatically indented. (Have the
422 line-block directive begin a block quote to get an indented line
423 block.) Line blocks are useful for address blocks and verse (poetry,
424 song lyrics), where the structure of lines is significant. For
425 example, here's a classic::
427 "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by
428 Ewan McTeagle (for Lassie O'Shea):
432 Lend us a couple of bob till Thursday.
433 I'm absolutely skint.
434 But I'm expecting a postal order and I can pay you back
445 :Directive Type: "parsed-literal"
446 :Doctree Element: literal_block_
447 :Directive Arguments: None.
448 :Directive Options: `:class:`_, `:name:`_
449 :Directive Content: Becomes the body of the literal block.
451 Unlike an ordinary literal block, the "parsed-literal" directive
452 constructs a literal block where the text is parsed for inline markup.
453 It is equivalent to a `line block`_ with different rendering:
454 typically in a typewriter/monospaced typeface, like an ordinary
455 literal block. Parsed literal blocks are useful for adding hyperlinks
458 However, care must be taken with the text, because inline markup is
459 recognized and there is no protection from parsing. Backslash-escapes
460 may be necessary to prevent unintended parsing. And because the
461 markup characters are removed by the parser, care must also be taken
462 with vertical alignment. Parsed "ASCII art" is tricky, and extra
463 whitespace may be necessary.
465 For example, all the element names in this content model are links::
469 ( (title_, subtitle_?)?,
471 (docinfo_, transition_?)?,
472 `%structure.model;`_ )
477 :Directive Type: "code"
478 :Doctree Element: literal_block_, `inline elements`_
479 :Directive Arguments: One, optional (formal language).
480 :Directive Options: name, class, number-lines.
481 :Directive Content: Becomes the body of the literal block.
482 :Configuration Setting: syntax_highlight_.
484 (New in Docutils 0.9)
486 The "code" directive constructs a literal block. If the code language is
487 specified, the content is parsed by the Pygments_ syntax highlighter and
488 tokens are stored in nested `inline elements`_ with class arguments
489 according to their syntactic category. The actual highlighting requires
490 a style-sheet (e.g. one `generated by Pygments`__, see the
491 `sandbox/stylesheets`__ for examples).
493 The parsing can be turned off with the syntax_highlight_ configuration
494 setting and command line option or by specifying the language as `:class:`_
495 option instead of directive argument. This also avoids warnings
496 when Pygments_ is not installed or the language is not in the
497 `supported languages and markup formats`_.
499 For inline code, use the `"code" role`_.
501 __ http://pygments.org/docs/cmdline/#generating-styles
502 __ http://docutils.sourceforge.net/sandbox/stylesheets/
503 .. _Pygments: http://pygments.org/
504 .. _syntax_highlight: ../../user/config.html#syntax-highlight
505 .. _supported languages and markup formats: http://pygments.org/languages/
506 .. _"code" role: roles.html#code
509 The following options are recognized:
511 ``number-lines`` : [start line number]
512 Precede every line with a line number.
513 The optional argument is the number of the first line (defaut 1).
515 and the common options `:class:`_ and `:name:`_.
518 The content of the following directive ::
526 is parsed and marked up as Python source code.
532 :Directive Type: "math"
533 :Doctree Element: math_block_
534 :Directive Arguments: One, optional: prepended to content.
535 :Directive Options: `:class:`_, `:name:`_
536 :Directive Content: Becomes the body of the math block.
537 (Content blocks separated by a blank line are put in
538 adjacent math blocks.)
539 :Configuration Setting: math_output_
541 (New in Docutils 0.8)
543 The "math" directive inserts blocks with mathematical content
544 (display formulas, equations) into the document. The input format is
545 *LaTeX math syntax*\ [#math-syntax]_ with support for Unicode
546 symbols, for example::
550 α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)
552 Support is limited to a subset of *LaTeX math* by the conversion
553 required for many output formats. For HTML, the `math_output`_
554 configuration setting (or the corresponding ``--math-output``
555 command line option) select between alternative output formats with
556 different subsets of supported elements. If a writer does not
557 support math typesetting at all, the content is inserted verbatim.
559 .. [#math-syntax] The supported LaTeX commands include AMS extensions
560 (see, e.g., the `Short Math Guide`_).
563 For inline formulas, use the `"math" role`_.
565 .. _Short Math Guide: ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf
566 .. _"math" role: roles.html#math
567 .. _math_output: ../../user/config.html#math-output
572 :Directive Type: "rubric"
573 :Doctree Element: rubric_
574 :Directive Arguments: 1, required (rubric text).
575 :Directive Options: `:class:`_, `:name:`_
576 :Directive Content: None.
580 rubric n. 1. a title, heading, or the like, in a manuscript,
581 book, statute, etc., written or printed in red or otherwise
582 distinguished from the rest of the text. ...
584 -- Random House Webster's College Dictionary, 1991
586 The "rubric" directive inserts a "rubric" element into the document
587 tree. A rubric is like an informal heading that doesn't correspond to
588 the document's structure.
594 :Directive Type: "epigraph"
595 :Doctree Element: block_quote_
596 :Directive Arguments: None.
597 :Directive Options: None.
598 :Directive Content: Interpreted as the body of the block quote.
600 An epigraph is an apposite (suitable, apt, or pertinent) short
601 inscription, often a quotation or poem, at the beginning of a document
604 The "epigraph" directive produces an "epigraph"-class block quote.
605 For example, this input::
609 No matter where you go, there you are.
613 becomes this document tree fragment::
615 <block_quote classes="epigraph">
617 No matter where you go, there you are.
625 :Directive Type: "highlights"
626 :Doctree Element: block_quote_
627 :Directive Arguments: None.
628 :Directive Options: None.
629 :Directive Content: Interpreted as the body of the block quote.
631 Highlights summarize the main points of a document or section, often
632 consisting of a list.
634 The "highlights" directive produces a "highlights"-class block quote.
635 See Epigraph_ above for an analogous example.
641 :Directive Type: "pull-quote"
642 :Doctree Element: block_quote_
643 :Directive Arguments: None.
644 :Directive Options: None.
645 :Directive Content: Interpreted as the body of the block quote.
647 A pull-quote is a small selection of text "pulled out and quoted",
648 typically in a larger typeface. Pull-quotes are used to attract
649 attention, especially in long articles.
651 The "pull-quote" directive produces a "pull-quote"-class block quote.
652 See Epigraph_ above for an analogous example.
658 :Directive Type: "compound"
659 :Doctree Element: compound_
660 :Directive Arguments: None.
661 :Directive Options: `:class:`_, `:name:`_
662 :Directive Content: Interpreted as body elements.
664 (New in Docutils 0.3.6)
666 The "compound" directive is used to create a compound paragraph, which
667 is a single logical paragraph containing multiple physical body
668 elements such as simple paragraphs, literal blocks, tables, lists,
669 etc., instead of directly containing text and inline elements. For
674 The 'rm' command is very dangerous. If you are logged
675 in as root and enter ::
680 you will erase the entire contents of your file system.
682 In the example above, a literal block is "embedded" within a sentence
683 that begins in one physical paragraph and ends in another.
687 The "compound" directive is *not* a generic block-level container
688 like HTML's ``<div>`` element. Do not use it only to group a
689 sequence of elements, or you may get unexpected results.
691 If you need a generic block-level container, please use the
692 container_ directive, described below.
694 Compound paragraphs are typically rendered as multiple distinct text
695 blocks, with the possibility of variations to emphasize their logical
698 * If paragraphs are rendered with a first-line indent, only the first
699 physical paragraph of a compound paragraph should have that indent
700 -- second and further physical paragraphs should omit the indents;
701 * vertical spacing between physical elements may be reduced;
708 :Directive Type: "container"
709 :Doctree Element: container_
710 :Directive Arguments: One or more, optional (class names).
711 :Directive Options: `:name:`_
712 :Directive Content: Interpreted as body elements.
714 (New in Docutils 0.3.10)
716 The "container" directive surrounds its contents (arbitrary body
717 elements) with a generic block-level "container" element. Combined
718 with the optional "classes_" attribute argument(s), this is an
719 extension mechanism for users & applications. For example::
721 .. container:: custom
723 This paragraph might be rendered in a custom way.
725 Parsing the above results in the following pseudo-XML::
727 <container classes="custom">
729 This paragraph might be rendered in a custom way.
731 The "container" directive is the equivalent of HTML's ``<div>``
732 element. It may be used to group a sequence of elements for user- or
733 application-specific purposes.
741 Formal tables need more structure than the reStructuredText syntax
742 supplies. Tables may be given titles with the table_ directive.
743 Sometimes reStructuredText tables are inconvenient to write, or table
744 data in a standard format is readily available. The csv-table_
745 directive supports CSV data.
751 :Directive Type: "table"
752 :Doctree Element: table_
753 :Directive Arguments: 1, optional (table title).
754 :Directive Options: Possible (see below).
755 :Directive Content: A normal reStructuredText table.
757 (New in Docutils 0.3.1)
759 The "table" directive is used to associate a
760 title with a table or specify options, e.g.::
762 .. table:: Truth table for "not"
773 The following options are recognized:
775 ``align`` : "left", "center", or "right"
776 The horizontal alignment of the table.
777 (New in Docutils 0.13)
779 ``widths`` : "auto", "grid" or a list of integers
780 A comma- or space-separated list of column widths.
781 The default is the width of the input columns (in characters).
783 The special values "auto" or "grid" may be used by writers to decide
784 whether to delegate the determination of column widths to the backend
785 (LaTeX, the HTML browser, ...).
786 See also the `table_style`_ configuration option.
788 and the common options `:class:`_ and `:name:`_.
790 .. _table_style: ../../user/config.html#table-style-html4css1-writer
797 :Directive Type: "csv-table"
798 :Doctree Element: table_
799 :Directive Arguments: 1, optional (table title).
800 :Directive Options: Possible (see below).
801 :Directive Content: A CSV (comma-separated values) table.
805 The "csv-table" directive's ":file:" and ":url:" options represent
806 a potential security holes. They can be disabled with the
807 "file_insertion_enabled_" runtime setting.
809 (New in Docutils 0.3.4)
811 The "csv-table" directive is used to create a table from CSV
812 (comma-separated values) data. CSV is a common data format generated
813 by spreadsheet applications and commercial databases. The data may be
814 internal (an integral part of the document) or external (a separate
819 .. csv-table:: Frozen Delights!
820 :header: "Treat", "Quantity", "Description"
823 "Albatross", 2.99, "On a stick!"
824 "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
825 crunchy, now would it?"
826 "Gannet Ripple", 1.99, "On a stick!"
828 Block markup and inline markup within cells is supported. Line ends
829 are recognized within cells.
833 * There is no support for checking that the number of columns in each
834 row is the same. However, this directive supports CSV generators
835 that do not insert "empty" entries at the end of short rows, by
836 automatically adding empty entries.
838 .. Add "strict" option to verify input?
840 .. [#whitespace-delim] Whitespace delimiters are supported only for external
843 .. [#ASCII-char] With Python 2, the valuess for the ``delimiter``,
844 ``quote``, and ``escape`` options must be ASCII characters. (The csv
845 module does not support Unicode and all non-ASCII characters are
846 encoded as multi-byte utf-8 string). This limitation does not exist
849 The following options are recognized:
851 ``widths`` : integer [, integer...] or "auto"
852 A comma- or space-separated list of relative column widths. The
853 default is equal-width columns (100%/#columns).
855 The special value "auto" may be used by writers to decide
856 whether to delegate the determination of column widths to the backend
857 (LaTeX, the HTML browser, ...).
859 ``header-rows`` : integer
860 The number of rows of CSV data to use in the table header.
863 ``stub-columns`` : integer
864 The number of table columns to use as stubs (row titles, on the
865 left). Defaults to 0.
867 ``header`` : CSV data
868 Supplemental data for the table header, added independently of and
869 before any ``header-rows`` from the main CSV data. Must use the
870 same CSV format as the main CSV data.
872 ``file`` : string (newlines removed)
873 The local filesystem path to a CSV data file.
875 ``url`` : string (whitespace removed)
876 An Internet URL reference to a CSV data file.
878 ``encoding`` : name of text encoding
879 The text encoding of the external CSV data (file or URL).
880 Defaults to the document's encoding (if specified).
882 ``delim`` : char | "tab" | "space" [#whitespace-delim]_
883 A one-character string\ [#ASCII-char]_ used to separate fields.
884 Defaults to ``,`` (comma). May be specified as a Unicode code
885 point; see the unicode_ directive for syntax details.
888 A one-character string\ [#ASCII-char]_ used to quote elements
889 containing the delimiter or which start with the quote
890 character. Defaults to ``"`` (quote). May be specified as a
891 Unicode code point; see the unicode_ directive for syntax
895 Treat whitespace immediately following the delimiter as
896 significant. The default is to ignore such whitespace.
899 A one-character\ [#ASCII-char]_ string used to escape the
900 delimiter or quote characters. May be specified as a Unicode
901 code point; see the unicode_ directive for syntax details. Used
902 when the delimiter is used in an unquoted field, or when quote
903 characters are used within a field. The default is to double-up
904 the character, e.g. "He said, ""Hi!"""
906 .. Add another possible value, "double", to explicitly indicate
909 ``align`` : "left", "center", or "right"
910 The horizontal alignment of the table.
911 (New in Docutils 0.13)
913 and the common options `:class:`_ and `:name:`_.
919 :Directive Type: "list-table"
920 :Doctree Element: table_
921 :Directive Arguments: 1, optional (table title).
922 :Directive Options: Possible (see below).
923 :Directive Content: A uniform two-level bullet list.
925 (New in Docutils 0.3.8. This is an initial implementation; `further
926 ideas`__ may be implemented in the future.)
928 __ ../../dev/rst/alternatives.html#list-driven-tables
930 The "list-table" directive is used to create a table from data in a
931 uniform two-level bullet list. "Uniform" means that each sublist
932 (second-level list) must contain the same number of list items.
936 .. list-table:: Frozen Delights!
948 - If we took the bones out, it wouldn't be
949 crunchy, now would it?
954 The following options are recognized:
956 ``widths`` : integer [integer...] or "auto"
957 A comma- or space-separated list of relative column widths. The
958 default is equal-width columns (100%/#columns).
960 The special value "auto" may be used by writers to decide
961 whether to delegate the determination of column widths to the backend
962 (LaTeX, the HTML browser, ...).
964 ``header-rows`` : integer
965 The number of rows of list data to use in the table header.
968 ``stub-columns`` : integer
969 The number of table columns to use as stubs (row titles, on the
970 left). Defaults to 0.
972 ``align`` : "left", "center", or "right"
973 The horizontal alignment of the table.
974 (New in Docutils 0.13)
976 and the common options `:class:`_ and `:name:`_.
988 :Directive Type: "contents"
989 :Doctree Elements: pending_, topic_
990 :Directive Arguments: One, optional: title.
991 :Directive Options: Possible.
992 :Directive Content: None.
994 The "contents" directive generates a table of contents (TOC) in a
995 topic_. Topics, and therefore tables of contents, may occur anywhere
996 a section or transition may occur. Body elements and topics may not
997 contain tables of contents.
999 Here's the directive in its simplest form::
1003 Language-dependent boilerplate text will be used for the title. The
1004 English default title text is "Contents".
1006 An explicit title may be specified::
1008 .. contents:: Table of Contents
1010 The title may span lines, although it is not recommended::
1012 .. contents:: Here's a very long Table of
1015 Options may be specified for the directive, using a field list::
1017 .. contents:: Table of Contents
1020 If the default title is to be used, the options field list may begin
1021 on the same line as the directive marker::
1023 .. contents:: :depth: 2
1025 The following options are recognized:
1028 The number of section levels that are collected in the table of
1029 contents. The default is unlimited depth.
1031 ``local`` : flag (empty)
1032 Generate a local table of contents. Entries will only include
1033 subsections of the section in which the directive is given. If no
1034 explicit title is given, the table of contents will not be titled.
1036 ``backlinks`` : "entry" or "top" or "none"
1037 Generate links from section headers back to the table of contents
1038 entries, the table of contents itself, or generate no backlinks.
1041 Set a `"classes"`_ attribute value on the topic element. See the
1042 class_ directive below.
1046 .. _section-numbering:
1048 Automatic Section Numbering
1049 ===========================
1051 :Directive Type: "sectnum" or "section-numbering" (synonyms)
1052 :Doctree Elements: pending_, generated_
1053 :Directive Arguments: None.
1054 :Directive Options: Possible.
1055 :Directive Content: None.
1056 :Configuration Setting: sectnum_xform_
1058 The "sectnum" (or "section-numbering") directive automatically numbers
1059 sections and subsections in a document (if not disabled by the
1060 ``--no-section-numbering`` command line option or the `sectnum_xform`_
1061 configuration setting).
1063 Section numbers are of the "multiple enumeration" form, where each
1064 level has a number, separated by periods. For example, the title of section
1065 1, subsection 2, subsubsection 3 would have "1.2.3" prefixed.
1067 The "sectnum" directive does its work in two passes: the initial parse
1068 and a transform. During the initial parse, a "pending" element is
1069 generated which acts as a placeholder, storing any options internally.
1070 At a later stage in the processing, the "pending" element triggers a
1071 transform, which adds section numbers to titles. Section numbers are
1072 enclosed in a "generated" element, and titles have their "auto"
1073 attribute set to "1".
1075 The following options are recognized:
1078 The number of section levels that are numbered by this directive.
1079 The default is unlimited depth.
1082 An arbitrary string that is prefixed to the automatically
1083 generated section numbers. It may be something like "3.2.", which
1084 will produce "3.2.1", "3.2.2", "3.2.2.1", and so on. Note that
1085 any separating punctuation (in the example, a period, ".") must be
1086 explicitly provided. The default is no prefix.
1089 An arbitrary string that is appended to the automatically
1090 generated section numbers. The default is no suffix.
1093 The value that will be used for the first section number.
1094 Combined with ``prefix``, this may be used to force the right
1095 numbering for a document split over several source files. The
1098 .. _sectnum_xform: ../../user/config.html#sectnum-xform
1104 Document Header & Footer
1105 ========================
1107 :Directive Types: "header" and "footer"
1108 :Doctree Elements: decoration_, header, footer
1109 :Directive Arguments: None.
1110 :Directive Options: None.
1111 :Directive Content: Interpreted as body elements.
1113 (New in Docutils 0.3.8)
1115 The "header" and "footer" directives create document decorations,
1116 useful for page navigation, notes, time/datestamp, etc. For example::
1118 .. header:: This space for rent.
1120 This will add a paragraph to the document header, which will appear at
1121 the top of the generated web page or at the top of every printed page.
1123 These directives may be used multiple times, cumulatively. There is
1124 currently support for only one header and footer.
1128 While it is possible to use the "header" and "footer" directives to
1129 create navigational elements for web pages, you should be aware
1130 that Docutils is meant to be used for *document* processing, and
1131 that a navigation bar is not typically part of a document.
1133 Thus, you may soon find Docutils' abilities to be insufficient for
1134 these purposes. At that time, you should consider using a
1135 documentation generator like Sphinx_ rather than the "header" and
1136 "footer" directives.
1138 .. _Sphinx: http://sphinx-doc.org/
1140 In addition to the use of these directives to populate header and
1141 footer content, content may also be added automatically by the
1142 processing system. For example, if certain runtime settings are
1143 enabled, the document footer is populated with processing information
1144 such as a datestamp, a link to `the Docutils website`_, etc.
1146 .. _the Docutils website: http://docutils.sourceforge.net
1158 :Directive Type: "target-notes"
1159 :Doctree Elements: pending_, footnote_, footnote_reference_
1160 :Directive Arguments: None.
1161 :Directive Options: `:class:`_, `:name:`_
1162 :Directive Options: Possible.
1163 :Directive Content: None.
1165 The "target-notes" directive creates a footnote for each external
1166 target in the text, and corresponding footnote references after each
1167 reference. For every explicit target (of the form, ``.. _target name:
1168 URL``) in the text, a footnote will be generated containing the
1169 visible URL as content.
1175 **NOT IMPLEMENTED YET**
1177 :Directive Type: "footnotes"
1178 :Doctree Elements: pending_, topic_
1179 :Directive Arguments: None?
1180 :Directive Options: Possible?
1181 :Directive Content: None.
1189 **NOT IMPLEMENTED YET**
1191 :Directive Type: "citations"
1192 :Doctree Elements: pending_, topic_
1193 :Directive Arguments: None?
1194 :Directive Options: Possible?
1195 :Directive Content: None.
1207 :Directive Type: "meta"
1208 :Doctree Element: meta (non-standard)
1209 :Directive Arguments: None.
1210 :Directive Options: None.
1211 :Directive Content: Must contain a flat field list.
1213 The "meta" directive is used to specify HTML metadata stored in HTML
1214 META tags. "Metadata" is data about data, in this case data about web
1215 pages. Metadata is used to describe and classify web pages in the
1216 World Wide Web, in a form that is easy for search engines to extract
1219 Within the directive block, a flat field list provides the syntax for
1220 metadata. The field name becomes the contents of the "name" attribute
1221 of the META tag, and the field body (interpreted as a single string
1222 without inline markup) becomes the contents of the "content"
1223 attribute. For example::
1226 :description: The reStructuredText plaintext markup language
1227 :keywords: plaintext, markup language
1229 This would be converted to the following HTML::
1231 <meta name="description"
1232 content="The reStructuredText plaintext markup language">
1233 <meta name="keywords" content="plaintext, markup language">
1235 Support for other META attributes ("http-equiv", "scheme", "lang",
1236 "dir") are provided through field arguments, which must be of the form
1240 :description lang=en: An amusing story
1241 :description lang=fr: Une histoire amusante
1243 And their HTML equivalents::
1245 <meta name="description" lang="en" content="An amusing story">
1246 <meta name="description" lang="fr" content="Une histoire amusante">
1248 Some META tags use an "http-equiv" attribute instead of the "name"
1249 attribute. To specify "http-equiv" META tags, simply omit the name::
1252 :http-equiv=Content-Type: text/html; charset=ISO-8859-1
1256 <meta http-equiv="Content-Type"
1257 content="text/html; charset=ISO-8859-1">
1263 **NOT IMPLEMENTED YET**
1265 Non-standard element: imagemap.
1268 -----------------------------------------
1269 Directives for Substitution Definitions
1270 -----------------------------------------
1272 The directives in this section may only be used in substitution
1273 definitions. They may not be used directly, in standalone context.
1274 The `image`_ directive may be used both in substitution definitions
1275 and in the standalone context.
1283 :Directive Type: "replace"
1284 :Doctree Element: Text & `inline elements`_
1285 :Directive Arguments: None.
1286 :Directive Options: None.
1287 :Directive Content: A single paragraph; may contain inline markup.
1289 The "replace" directive is used to indicate replacement text for a
1290 substitution reference. It may be used within substitution
1291 definitions only. For example, this directive can be used to expand
1294 .. |reST| replace:: reStructuredText
1296 Yes, |reST| is a long word, so I can't blame anyone for wanting to
1299 As reStructuredText doesn't support nested inline markup, the only way
1300 to create a reference with styled text is to use substitutions with
1301 the "replace" directive::
1303 I recommend you try |Python|_.
1305 .. |Python| replace:: Python, *the* best language around
1306 .. _Python: http://www.python.org/
1311 Unicode Character Codes
1312 =======================
1314 :Directive Type: "unicode"
1315 :Doctree Element: Text
1316 :Directive Arguments: One or more, required (Unicode character codes,
1317 optional text, and comments).
1318 :Directive Options: Possible.
1319 :Directive Content: None.
1321 The "unicode" directive converts Unicode character codes (numerical
1322 values) to characters, and may be used in substitution definitions
1325 The arguments, separated by spaces, can be:
1327 * **character codes** as
1329 - decimal numbers or
1331 - hexadecimal numbers, prefixed by ``0x``, ``x``, ``\x``, ``U+``,
1332 ``u``, or ``\u`` or as XML-style hexadecimal character entities,
1335 * **text**, which is used as-is.
1337 Text following " .. " is a comment and is ignored. The spaces between
1338 the arguments are ignored and thus do not appear in the output.
1339 Hexadecimal codes are case-insensitive.
1341 For example, the following text::
1343 Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|
1344 all rights reserved.
1346 .. |copy| unicode:: 0xA9 .. copyright sign
1347 .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
1348 .. with trademark sign
1349 .. |---| unicode:: U+02014 .. em dash
1354 Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|
1355 all rights reserved.
1357 .. |copy| unicode:: 0xA9 .. copyright sign
1358 .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
1359 .. with trademark sign
1360 .. |---| unicode:: U+02014 .. em dash
1363 The following options are recognized:
1366 Whitespace to the left of the substitution reference is removed.
1369 Whitespace to the right of the substitution reference is removed.
1372 Equivalent to ``ltrim`` plus ``rtrim``; whitespace on both sides
1373 of the substitution reference is removed.
1379 :Directive Type: "date"
1380 :Doctree Element: Text
1381 :Directive Arguments: One, optional (date format).
1382 :Directive Options: None.
1383 :Directive Content: None.
1385 The "date" directive generates the current local date and inserts it
1386 into the document as text. This directive may be used in substitution
1389 The optional directive content is interpreted as the desired date
1390 format, using the same codes as Python's time.strftime function. The
1391 default format is "%Y-%m-%d" (ISO 8601 date), but time fields can also
1395 .. |time| date:: %H:%M
1397 Today's date is |date|.
1399 This document was generated on |date| at |time|.
1408 Including an External Document Fragment
1409 =======================================
1411 :Directive Type: "include"
1412 :Doctree Elements: Depend on data being included
1413 (literal_block_ with ``code`` or ``literal`` option).
1414 :Directive Arguments: One, required (path to the file to include).
1415 :Directive Options: Possible.
1416 :Directive Content: None.
1417 :Configuration Setting: file_insertion_enabled_
1421 The "include" directive represents a potential security hole. It
1422 can be disabled with the "file_insertion_enabled_" runtime setting.
1424 .. _file_insertion_enabled: ../../user/config.html#file-insertion-enabled
1426 The "include" directive reads a text file. The directive argument is
1427 the path to the file to be included, relative to the document
1428 containing the directive. Unless the options ``literal`` or ``code``
1429 are given, the file is parsed in the current document's context at the
1430 point of the directive. For example::
1432 This first example will be parsed at the document level, and can
1433 thus contain any construct, including section headers.
1435 .. include:: inclusion.txt
1437 Back in the main document.
1439 This second example will be parsed in a block quote context.
1440 Therefore it may only contain body elements. It may not
1441 contain section headers.
1443 .. include:: inclusion.txt
1445 If an included document fragment contains section structure, the title
1446 adornments must match those of the master document.
1448 Standard data files intended for inclusion in reStructuredText
1449 documents are distributed with the Docutils source code, located in
1450 the "docutils" package in the ``docutils/parsers/rst/include``
1451 directory. To access these files, use the special syntax for standard
1452 "include" data files, angle brackets around the file name::
1454 .. include:: <isonum.txt>
1456 The current set of standard "include" data files consists of sets of
1457 substitution definitions. See `reStructuredText Standard Definition
1458 Files`__ for details.
1462 The following options are recognized:
1464 ``start-line`` : integer
1465 Only the content starting from this line will be included.
1466 (As usual in Python, the first line has index 0 and negative values
1467 count from the end.)
1469 ``end-line`` : integer
1470 Only the content up to (but excluding) this line will be included.
1472 ``start-after`` : text to find in the external data file
1473 Only the content after the first occurrence of the specified text
1476 ``end-before`` : text to find in the external data file
1477 Only the content before the first occurrence of the specified text
1478 (but after any ``after`` text) will be included.
1480 ``literal`` : flag (empty)
1481 The entire included text is inserted into the document as a single
1484 ``code`` : formal language (optional)
1485 The argument and the content of the included file are passed to
1486 the code_ directive (useful for program listings).
1487 (New in Docutils 0.9)
1489 ``number-lines`` : [start line number]
1490 Precede every code line with a line number.
1491 The optional argument is the number of the first line (defaut 1).
1492 Works only with ``code`` or ``literal``.
1493 (New in Docutils 0.9)
1495 ``encoding`` : name of text encoding
1496 The text encoding of the external data file. Defaults to the
1497 document's input_encoding_.
1499 .. _input_encoding: ../../user/config.html#input-encoding
1501 ``tab-width`` : integer
1502 Number of spaces for hard tab expansion.
1503 A negative value prevents expansion of hard tabs. Defaults to the
1504 tab_width_ configuration setting.
1506 .. _tab_width: ../../user/config.html#tab-width
1509 With ``code`` or ``literal`` the common options `:class:`_ and
1510 `:name:`_ are recognized as well.
1512 Combining ``start/end-line`` and ``start-after/end-before`` is possible. The
1513 text markers will be searched in the specified lines (further limiting the
1518 Raw Data Pass-Through
1519 =====================
1521 :Directive Type: "raw"
1522 :Doctree Element: raw_
1523 :Directive Arguments: One or more, required (output format types).
1524 :Directive Options: Possible.
1525 :Directive Content: Stored verbatim, uninterpreted. None (empty) if a
1526 "file" or "url" option given.
1527 :Configuration Setting: raw_enabled_
1531 The "raw" directive represents a potential security hole. It can
1532 be disabled with the "raw_enabled_" or "file_insertion_enabled_"
1535 .. _raw_enabled: ../../user/config.html#raw-enabled
1539 The "raw" directive is a stop-gap measure allowing the author to
1540 bypass reStructuredText's markup. It is a "power-user" feature
1541 that should not be overused or abused. The use of "raw" ties
1542 documents to specific output formats and makes them less portable.
1544 If you often need to use the "raw" directive or a "raw"-derived
1545 interpreted text role, that is a sign either of overuse/abuse or
1546 that functionality may be missing from reStructuredText. Please
1547 describe your situation in a message to the Docutils-users_ mailing
1550 .. _Docutils-users: ../../user/mailing-lists.html#docutils-users
1552 The "raw" directive indicates non-reStructuredText data that is to be
1553 passed untouched to the Writer. The names of the output formats are
1554 given in the directive arguments. The interpretation of the raw data
1555 is up to the Writer. A Writer may ignore any raw output not matching
1558 For example, the following input would be passed untouched by an HTML
1563 <hr width=50 size=10>
1565 A LaTeX Writer could insert the following raw content into its
1570 \setlength{\parindent}{0pt}
1572 Raw data can also be read from an external file, specified in a
1573 directive option. In this case, the content block must be empty. For
1577 :file: inclusion.html
1579 Inline equivalents of the "raw" directive can be defined via
1580 `custom interpreted text roles`_ derived from the `"raw" role`_.
1582 The following options are recognized:
1584 ``file`` : string (newlines removed)
1585 The local filesystem path of a raw data file to be included.
1587 ``url`` : string (whitespace removed)
1588 An Internet URL reference to a raw data file to be included.
1590 ``encoding`` : name of text encoding
1591 The text encoding of the external raw data (file or URL).
1592 Defaults to the document's encoding (if specified).
1594 .. _"raw" role: roles.html#raw
1602 :Directive Type: "class"
1603 :Doctree Element: pending_
1604 :Directive Arguments: One or more, required (class names / attribute
1606 :Directive Options: None.
1607 :Directive Content: Optional. If present, it is interpreted as body
1610 The "class" directive sets the `"classes"`_ attribute value on its content
1611 or on the first immediately following [#]_ non-comment element [#]_. For
1612 details of the "classes" attribute, see the `classes entry in The Docutils
1615 The directive argument consists of one or more space-separated class
1616 names. The names are transformed to conform to the regular expression
1617 ``[a-z](-?[a-z0-9]+)*`` by converting
1619 * alphabetic characters to lowercase,
1620 * accented characters to the base character,
1621 * non-alphanumeric characters to hyphens,
1622 * consecutive hyphens into one hyphen.
1624 For example "Rot-Gelb.Blau Grün:+2008" becomes "rot-gelb-blau grun-2008".
1625 (For the rationale_, see below.)
1627 __ ../doctree.html#classes
1633 This is a "special" paragraph.
1635 .. class:: exceptional remarkable
1637 An Exceptional Section
1638 ======================
1640 This is an ordinary paragraph.
1648 The text above is parsed and transformed into this doctree fragment::
1650 <paragraph classes="special">
1651 This is a "special" paragraph.
1652 <section classes="exceptional remarkable">
1654 An Exceptional Section
1656 This is an ordinary paragraph.
1657 <paragraph classes="multiple">
1659 <paragraph classes="multiple">
1663 .. [#] This is also true, if the class directive is "nested" at the end of
1664 an indented text block, for example::
1666 .. note:: the class values set in this directive-block do not apply to
1667 the note but the next paragraph.
1671 This is a paragraph with class value "special".
1673 This allows the "classification" of individual list items (except the
1674 first, as a preceding class directive applies to the list as a whole)::
1678 .. class:: classy item
1680 * second item, with class argument
1682 .. [#] To set a "classes" attribute value on a block quote, the
1683 "class" directive must be followed by an empty comment::
1685 .. class:: highlights
1690 Without the empty comment, the indented text would be interpreted as the
1691 "class" directive's content, and the classes would be applied to each
1692 element (paragraph, in this case) individually, instead of to the block
1697 .. topic:: Rationale for "classes" Attribute Value Conversion
1700 Docutils identifiers are converted to conform to the regular
1701 expression ``[a-z](-?[a-z0-9]+)*``. For HTML + CSS compatibility,
1702 identifiers (the "classes" and "id" attributes) should have no
1703 underscores, colons, or periods. Hyphens may be used.
1705 - The `HTML 4.01 spec`_ defines identifiers based on SGML tokens:
1707 ID and NAME tokens must begin with a letter ([A-Za-z]) and
1708 may be followed by any number of letters, digits ([0-9]),
1709 hyphens ("-"), underscores ("_"), colons (":"), and periods
1712 - The `CSS1 spec`_ defines identifiers based on the "name" token
1713 ("flex" tokenizer notation below; "latin1" and "escape" 8-bit
1714 characters have been replaced with XML entities)::
1716 unicode \\[0-9a-f]{1,4}
1717 latin1 [¡-ÿ]
1718 escape {unicode}|\\[ -~¡-ÿ]
1719 nmchar [-A-Za-z0-9]|{latin1}|{escape}
1722 The CSS rule does not include underscores ("_"), colons (":"), or
1723 periods ("."), therefore "classes" and "id" attributes should not
1724 contain these characters. Combined with HTML's requirements (the
1725 first character must be a letter; no "unicode", "latin1", or
1726 "escape" characters), this results in the regular expression
1727 ``[A-Za-z][-A-Za-z0-9]*``. Docutils adds a normalisation by
1728 downcasing and merge of consecutive hyphens.
1730 .. _HTML 4.01 spec: http://www.w3.org/TR/html401/
1731 .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1
1736 Custom Interpreted Text Roles
1737 =============================
1739 :Directive Type: "role"
1740 :Doctree Element: None; affects subsequent parsing.
1741 :Directive Arguments: Two; one required (new role name), one optional
1742 (base role name, in parentheses).
1743 :Directive Options: Possible (depends on base role).
1744 :Directive Content: depends on base role.
1746 (New in Docutils 0.3.2)
1748 The "role" directive dynamically creates a custom interpreted text
1749 role and registers it with the parser. This means that after
1750 declaring a role like this::
1754 the document may use the new "custom" role::
1756 An example of using :custom:`interpreted text`
1758 This will be parsed into the following document tree fragment::
1762 <inline classes="custom">
1765 The role must be declared in a document before it can be used.
1767 The new role may be based on an existing role, specified as a second
1768 argument in parentheses (whitespace optional)::
1770 .. role:: custom(emphasis)
1774 The parsed result is as follows::
1777 <emphasis classes="custom">
1780 A special case is the `"raw" role`_: derived roles enable
1781 inline `raw data pass-through`_, e.g.::
1783 .. role:: raw-role(raw)
1786 :raw-role:`raw text`
1788 If no base role is explicitly specified, a generic custom role is
1789 automatically used. Subsequent interpreted text will produce an
1790 "inline" element with a `"classes"`_ attribute, as in the first example
1793 With most roles, the ":class:" option can be used to set a "classes"
1794 attribute that is different from the role name. For example::
1799 :custom:`interpreted text`
1801 This is the parsed result::
1804 <inline classes="special">
1809 The following option is recognized by the "role" directive for most
1813 Set the `"classes"`_ attribute value on the element produced
1814 (``inline``, or element associated with a base class) when the
1815 custom interpreted text role is used. If no directive options are
1816 specified, a "class" option with the directive argument (role
1817 name) as the value is implied. See the class_ directive above.
1819 Specific base roles may support other options and/or directive
1820 content. See the `reStructuredText Interpreted Text Roles`_ document
1823 .. _reStructuredText Interpreted Text Roles: roles.html
1828 Setting the Default Interpreted Text Role
1829 =========================================
1831 :Directive Type: "default-role"
1832 :Doctree Element: None; affects subsequent parsing.
1833 :Directive Arguments: One, optional (new default role name).
1834 :Directive Options: None.
1835 :Directive Content: None.
1837 (New in Docutils 0.3.10)
1839 The "default-role" directive sets the default interpreted text role,
1840 the role that is used for interpreted text without an explicit role.
1841 For example, after setting the default role like this::
1843 .. default-role:: subscript
1845 any subsequent use of implicit-role interpreted text in the document
1846 will use the "subscript" role::
1848 An example of a `default` role.
1850 This will be parsed into the following document tree fragment::
1858 Custom roles may be used (see the "role_" directive above), but it
1859 must have been declared in a document before it can be set as the
1860 default role. See the `reStructuredText Interpreted Text Roles`_
1861 document for details of built-in roles.
1863 The directive may be used without an argument to restore the initial
1864 default interpreted text role, which is application-dependent. The
1865 initial default interpreted text role of the standard reStructuredText
1866 parser is "title-reference".
1869 Metadata Document Title
1870 =======================
1872 :Directive Type: "title"
1873 :Doctree Element: None.
1874 :Directive Arguments: 1, required (the title text).
1875 :Directive Options: None.
1876 :Directive Content: None.
1878 The "title" directive specifies the document title as metadata, which
1879 does not become part of the document body. It overrides a
1880 document-supplied title. For example, in HTML output the metadata
1881 document title appears in the title bar of the browser window.
1884 Restructuredtext-Test-Directive
1885 ===============================
1887 :Directive Type: "restructuredtext-test-directive"
1888 :Doctree Element: system_warning
1889 :Directive Arguments: None.
1890 :Directive Options: None.
1891 :Directive Content: Interpreted as a literal block.
1893 This directive is provided for test purposes only. (Nobody is
1894 expected to type in a name *that* long!) It is converted into a
1895 level-1 (info) system message showing the directive data, possibly
1896 followed by a literal block containing the rest of the directive
1903 Most of the directives that generate doctree elements support the following
1907 Set a `"classes"`_ attribute value on the doctree element generated by
1908 the directive. See also the class_ directive.
1911 Add `text` to the `"names"`_ attribute of the doctree element generated
1912 by the directive. This allows `hyperlink references`_ to the element
1913 using `text` as `reference name`_.
1915 Specifying the `name` option of a directive, e.g., ::
1920 is a concise syntax alternative to preceding it with a `hyperlink
1927 New in Docutils 0.8.
1930 .. _reference name: restructuredtext.html#reference-names
1931 .. _hyperlink target: restructuredtext.html#hyperlink-targets
1932 .. _hyperlink references: restructuredtext.html#hyperlink-references
1933 .. _"classes": ../doctree.html#classes
1934 .. _"names": ../doctree.html#names
1935 .. _admonition: ../doctree.html#admonition
1936 .. _block_quote: ../doctree.html#block-quote
1937 .. _caption: ../doctree.html#caption
1938 .. _compound: ../doctree.html#compound
1939 .. _container: ../doctree.html#container
1940 .. _decoration: ../doctree.html#decoration
1941 .. _figure: ../doctree.html#figure
1942 .. _footnote: ../doctree.html#footnote
1943 .. _footnote_reference: ../doctree.html#footnote-reference
1944 .. _generated: ../doctree.html#generated
1945 .. _image: ../doctree.html#image
1946 .. _inline elements: ../doctree.html#inline-elements
1947 .. _literal_block: ../doctree.html#literal-block
1948 .. _legend: ../doctree.html#legend
1949 .. _line_block: ../doctree.html#line-block
1950 .. _math_block: ../doctree.html#math-block
1951 .. _pending: ../doctree.html#pending
1952 .. _raw: ../doctree.html#raw
1953 .. _rubric: ../doctree.html#rubric
1954 .. _sidebar: ../doctree.html#sidebar
1955 .. _table: ../doctree.html#table
1956 .. _title: ../doctree.html#title
1957 .. _topic: ../doctree.html#topic
1964 indent-tabs-mode: nil
1965 sentence-end-double-space: t