{ "sectnum(docutils.parsers.rst.directives.parts.Sectnum)": { "is_markdown": true, "description": [ "## Automatic Section Numbering", "", "| | |", "|-|-|", "| Directive Type | \"sectnum\" or \"section-numbering\" (synonyms) |", "| Doctree Elements | [pending](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#pending), [generated](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#generated) |", "| Directive Arguments | None. |", "| Directive Options | Possible (see below). |", "| Directive Content | None. |", "| Configuration Setting | [sectnum_xform](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#sectnum-xform) |", "", "The \"sectnum\" (or \"section-numbering\") directive automatically numbers", "sections and subsections in a document (if not disabled by the", "`--no-section-numbering` command line option or the [sectnum_xform](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#sectnum-xform)", "configuration setting).", "", "Section numbers are of the \"multiple enumeration\" form, where each", "level has a number, separated by periods. For example, the title of section", "1, subsection 2, subsubsection 3 would have \"1.2.3\" prefixed.", "", "The \"sectnum\" directive does its work in two passes: the initial parse", "and a transform. During the initial parse, a \"pending\" element is", "generated which acts as a placeholder, storing any options internally.", "At a later stage in the processing, the \"pending\" element triggers a", "transform, which adds section numbers to titles. Section numbers are", "enclosed in a \"generated\" element, and titles have their \"auto\"", "attribute set to \"1\".", "", "The following options are recognized:", "", "`depth`: integer", "The number of section levels that are numbered by this directive.", "The default is unlimited depth.", "", "`prefix`: string", "An arbitrary string that is prefixed to the automatically", "generated section numbers. It may be something like \"3.2.\", which", "will produce \"3.2.1\", \"3.2.2\", \"3.2.2.1\", and so on. Note that", "any separating punctuation (in the example, a period, \".\") must be", "explicitly provided. The default is no prefix.", "", "`suffix`: string", "An arbitrary string that is appended to the automatically", "generated section numbers. The default is no suffix.", "", "`start`: integer", "The value that will be used for the first section number.", "Combined with `prefix`, this may be used to force the right", "numbering for a document split over several source files. The", "default is 1." ], "options": { "depth": "integer\nThe number of section levels that are numbered by this directive.\nThe default is unlimited depth.\n", "prefix": "string\nAn arbitrary string that is prefixed to the automatically\ngenerated section numbers. It may be something like \"3.2.\", which\nwill produce \"3.2.1\", \"3.2.2\", \"3.2.2.1\", and so on. Note that\nany separating punctuation (in the example, a period, \".\") must be\nexplicitly provided. The default is no prefix.\n", "suffix": "string\nAn arbitrary string that is appended to the automatically\ngenerated section numbers. The default is no suffix.\n", "start": "integer\nThe value that will be used for the first section number.\nCombined with `prefix`, this may be used to force the right\nnumbering for a document split over several source files. The\ndefault is 1.\n" }, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#automatic-section-numbering", "license": "https://docutils.sourceforge.io/docs/" }, "attention(docutils.parsers.rst.directives.admonitions.Attention)": { "is_markdown": true, "description": [ "## Specific Admonitions", "", "| | |", "|-|-|", "| Directive Types | \"attention\", \"caution\", \"danger\", \"error\", \"hint\",", "\"important\", \"note\", \"tip\", \"warning\", \"admonition\" |", "| Doctree Elements | attention, caution, danger, error, hint, important,", "note, tip, warning, [admonition](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#admonition), [title](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#title) |", "| Directive Arguments | None. |", "| Directive Options | [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33), [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) |", "| Directive Content | Interpreted as body elements. |", "", "Admonitions are specially marked \"topics\" that can appear anywhere an", "ordinary body element can. They contain arbitrary body elements.", "Typically, an admonition is rendered as an offset block in a document,", "sometimes outlined or shaded, with a title matching the admonition", "type. For example:", "", "```", ".. DANGER::", " Beware killer rabbits!", "```", "", "This directive might be rendered something like this:", "", "```", "+------------------------+", "| !DANGER! |", "| |", "| Beware killer rabbits! |", "+------------------------+", "```", "", "The following admonition directives have been implemented:", "- attention", "- caution", "- danger", "- error", "- hint", "- important", "- note", "- tip", "- warning", "", "Any text immediately following the directive indicator (on the same", "line and/or indented on following lines) is interpreted as a directive", "block and is parsed for normal body elements. For example, the", "following \"note\" admonition directive contains one paragraph and a", "bullet list consisting of two list items:", "", "```", ".. note:: This is a note admonition.", " This is the second line of the first paragraph.", "", " - The note contains all indented body elements", " following.", " - It includes this bullet list.", "```" ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#attention", "license": "https://docutils.sourceforge.io/docs/" }, "caution(docutils.parsers.rst.directives.admonitions.Caution)": { "is_markdown": true, "description": [ "## Specific Admonitions", "", "| | |", "|-|-|", "| Directive Types | \"attention\", \"caution\", \"danger\", \"error\", \"hint\",", "\"important\", \"note\", \"tip\", \"warning\", \"admonition\" |", "| Doctree Elements | attention, caution, danger, error, hint, important,", "note, tip, warning, [admonition](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#admonition), [title](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#title) |", "| Directive Arguments | None. |", "| Directive Options | [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33), [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) |", "| Directive Content | Interpreted as body elements. |", "", "Admonitions are specially marked \"topics\" that can appear anywhere an", "ordinary body element can. They contain arbitrary body elements.", "Typically, an admonition is rendered as an offset block in a document,", "sometimes outlined or shaded, with a title matching the admonition", "type. For example:", "", "```", ".. DANGER::", " Beware killer rabbits!", "```", "", "This directive might be rendered something like this:", "", "```", "+------------------------+", "| !DANGER! |", "| |", "| Beware killer rabbits! |", "+------------------------+", "```", "", "The following admonition directives have been implemented:", "- attention", "- caution", "- danger", "- error", "- hint", "- important", "- note", "- tip", "- warning", "", "Any text immediately following the directive indicator (on the same", "line and/or indented on following lines) is interpreted as a directive", "block and is parsed for normal body elements. For example, the", "following \"note\" admonition directive contains one paragraph and a", "bullet list consisting of two list items:", "", "```", ".. note:: This is a note admonition.", " This is the second line of the first paragraph.", "", " - The note contains all indented body elements", " following.", " - It includes this bullet list.", "```" ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#caution", "license": "https://docutils.sourceforge.io/docs/" }, "code(docutils.parsers.rst.directives.body.CodeBlock)": { "is_markdown": true, "description": [ "## Code", "", "| | |", "|-|-|", "| Directive Type | \"code\" |", "| Doctree Element | [literal_block](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#literal-block), [inline elements](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#inline-elements) |", "| Directive Arguments | One, optional (formal language). |", "| Directive Options | name, class, number-lines. |", "| Directive Content | Becomes the body of the literal block. |", "| Configuration Setting | [syntax_highlight](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#syntax-highlight). |", "", "The \"code\" directive constructs a literal block. If the code language is", "specified, the content is parsed by the [Pygments](https://pygments.org/) syntax highlighter and", "tokens are stored in nested [inline elements](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#inline-elements) with class arguments", "according to their syntactic category. The actual highlighting requires", "a style-sheet (e.g. one [generated by Pygments](https://pygments.org/docs/cmdline/#generating-styles), see the", "[sandbox/stylesheets](https://docutils.sourceforge.io/sandbox/stylesheets/) for examples).", "", "The parsing can be turned off with the [syntax_highlight](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#syntax-highlight) configuration", "setting and command line option or by specifying the language as [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33)", "option instead of directive argument. This also avoids warnings", "when [Pygments](https://pygments.org/) is not installed or the language is not in the", "[supported languages and markup formats](https://pygments.org/languages/).", "", "For inline code, use the [\"code\" role](https:/docutils.sourceforge.io/docs/ref/rst/roles.html#code).", "", "The following options are recognized:", "", "`number-lines`: [integer] (start line number)", "Precede every line with a line number.", "The optional argument is the number of the first line (default 1).", "", "and the common options [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33) and [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name).", "", "`Example::`: ", "The content of the following directive", "", "```", ".. code:: python", "", " def my_function():", " \"just a test\"", " print 8/2", "```", "", "is parsed and marked up as Python source code." ], "options": { "number-lines": "[integer] (start line number)\nPrecede every line with a line number.\nThe optional argument is the number of the first line (default 1).\n", "Example::": "\nThe content of the following directive\n\n```\n.. code:: python\n\n def my_function():\n \"just a test\"\n print 8/2\n```\n\nis parsed and marked up as Python source code.\n" }, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#code", "license": "https://docutils.sourceforge.io/docs/" }, "compound(docutils.parsers.rst.directives.body.Compound)": { "is_markdown": true, "description": [ "## Compound Paragraph", "", "| | |", "|-|-|", "| Directive Type | \"compound\" |", "| Doctree Element | [compound](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#compound) |", "| Directive Arguments | None. |", "| Directive Options | [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33), [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) |", "| Directive Content | Interpreted as body elements. |", "", "The \"compound\" directive is used to create a compound paragraph, which", "is a single logical paragraph containing multiple physical body", "elements such as simple paragraphs, literal blocks, tables, lists,", "etc., instead of directly containing text and inline elements. For", "example:", "", "```", ".. compound::", "", " The 'rm' command is very dangerous. If you are logged", " in as root and enter ::", "", " cd /", " rm -rf *", "", " you will erase the entire contents of your file system.", "```", "", "In the example above, a literal block is \"embedded\" within a sentence", "that begins in one physical paragraph and ends in another.", "", "The \"compound\" directive is not a generic block-level container", "like HTML's `
` element. Do not use it only to group a", "sequence of elements, or you may get unexpected results.", "", "If you need a generic block-level container, please use the", "[container](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#container) directive, described below.", "", "Compound paragraphs are typically rendered as multiple distinct text", "blocks, with the possibility of variations to emphasize their logical", "unity:", "- If paragraphs are rendered with a first-line indent, only the first", "physical paragraph of a compound paragraph should have that indent", "-- second and further physical paragraphs should omit the indents;", "- vertical spacing between physical elements may be reduced;", "- and so on." ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#compound-paragraph", "license": "https://docutils.sourceforge.io/docs/" }, "container(docutils.parsers.rst.directives.body.Container)": { "is_markdown": true, "description": [ "## Container", "", "| | |", "|-|-|", "| Directive Type | \"container\" |", "| Doctree Element | [container](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#container) |", "| Directive Arguments | One or more, optional (class names). |", "| Directive Options | [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) |", "| Directive Content | Interpreted as body elements. |", "", "The \"container\" directive surrounds its contents (arbitrary body", "elements) with a generic block-level \"container\" element. Combined", "with the optional \"[classes](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#classes)\" attribute argument(s), this is an", "extension mechanism for users & applications. For example:", "", "```", ".. container:: custom", "", " This paragraph might be rendered in a custom way.", "```", "", "Parsing the above results in the following pseudo-XML:", "", "```", "", " ", " This paragraph might be rendered in a custom way.", "```", "", "The \"container\" directive is the equivalent of HTML's `
`", "element. It may be used to group a sequence of elements for user- or", "application-specific purposes." ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#container", "license": "https://docutils.sourceforge.io/docs/" }, "csv-table(docutils.parsers.rst.directives.tables.CSVTable)": { "is_markdown": true, "description": [ "## CSV Table", "", "| | |", "|-|-|", "| Directive Type | \"csv-table\" |", "| Doctree Element | [table](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#table) |", "| Directive Arguments | One, optional (table title). |", "| Directive Options | Possible (see below). |", "| Directive Content | A CSV (comma-separated values) table. |", "", "The \"csv-table\" directive's \":file:\" and \":url:\" options represent", "a potential security holes. They can be disabled with the", "\"[file_insertion_enabled](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#file-insertion-enabled)\" runtime setting.", "", "The \"csv-table\" directive is used to create a table from CSV", "(comma-separated values) data. CSV is a common data format generated", "by spreadsheet applications and commercial databases. The data may be", "internal (an integral part of the document) or external (a separate", "file).", "- Block markup and inline markup within cells is supported. Line ends", "are recognized within cells.", "- There is no support for checking that the number of columns in each", "row is the same. The directive automatically adds empty entries at", "the end of short rows.", "Add \"strict\" option to verify input?", "Example:", "", "```", ".. csv-table:: Frozen Delights!", " :header: \"Treat\", \"Quantity\", \"Description\"", " :widths: 15, 10, 30", "", " \"Albatross\", 2.99, \"On a stick!\"", " \"Crunchy Frog\", 1.49, \"If we took the bones out, it wouldn't be", " crunchy, now would it?\"", " \"Gannet Ripple\", 1.99, \"On a stick!\"", "```", "", "The following options are recognized:", "", "`align`: \"left\", \"center\", or \"right\"", "The horizontal alignment of the table. (New in Docutils 0.13)", "", "`delim`: char | \"tab\" | \"space\" 4", "A one-character string5 used to separate fields.", "Defaults to `,` (comma). May be specified as a Unicode code", "point; see the [unicode](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#unicode) directive for syntax details.", "", "`encoding`: string", "The text encoding of the external CSV data (file or URL).", "Defaults to the document's [input_encoding](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#input-encoding).", "", "`escape`: char", "A one-character5 string used to escape the", "delimiter or quote characters. May be specified as a Unicode", "code point; see the [unicode](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#unicode) directive for syntax details. Used", "when the delimiter is used in an unquoted field, or when quote", "characters are used within a field. The default is to double-up", "the character, e.g. \"He said, \"\"Hi!\"\"\"", "Add another possible value, \"double\", to explicitly indicate", "the default case?", "`file`: string (newlines removed)", "The local filesystem path to a CSV data file.", "", "`header`: CSV data", "Supplemental data for the table header, added independently of and", "before any `header-rows` from the main CSV data. Must use the", "same CSV format as the main CSV data.", "", "`header-rows`: integer", "The number of rows of CSV data to use in the table header.", "Defaults to 0.", "", "`keepspace`: flag (empty)", "Treat whitespace immediately following the delimiter as", "significant. The default is to ignore such whitespace.", "", "`quote`: char", "A one-character string5 used to quote elements", "containing the delimiter or which start with the quote", "character. Defaults to `\"` (quote). May be specified as a", "Unicode code point; see the [unicode](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#unicode) directive for syntax", "details.", "", "`stub-columns`: integer", "The number of table columns to use as stubs (row titles, on the", "left). Defaults to 0.", "", "`url`: string (whitespace removed)", "An Internet URL reference to a CSV data file.", "", "`widths`: integer [integer...] or \"auto\"", "A list of relative column widths.", "The default is equal-width columns (100%/#columns).", "", "\"auto\" delegates the determination of column widths to the backend", "(LaTeX, the HTML browser, ...).", "", "`width`: [length](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#length-units) or [percentage](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#percentage-units)", "Sets the width of the table to the specified length or percentage", "of the line width. If omitted, the renderer determines the width", "of the table based on its contents or the column `widths`.", "", "and the common options [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33) and [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name).", "4", "Whitespace delimiters are supported only for external", "CSV files.", "5", "With Python\u00a02, the values for the `delimiter`,", "`quote`, and `escape` options must be ASCII characters. (The csv", "module does not support Unicode and all non-ASCII characters are", "encoded as multi-byte utf-8 string). This limitation does not exist", "under Python\u00a03." ], "options": { "align": "\"left\", \"center\", or \"right\"\nThe horizontal alignment of the table. (New in Docutils 0.13)\n", "delim": "char | \"tab\" | \"space\" 4\nA one-character string5 used to separate fields.\nDefaults to `,` (comma). May be specified as a Unicode code\npoint; see the [unicode](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#unicode) directive for syntax details.\n", "encoding": "string\nThe text encoding of the external CSV data (file or URL).\nDefaults to the document's [input_encoding](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#input-encoding).\n", "escape": "char\nA one-character5 string used to escape the\ndelimiter or quote characters. May be specified as a Unicode\ncode point; see the [unicode](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#unicode) directive for syntax details. Used\nwhen the delimiter is used in an unquoted field, or when quote\ncharacters are used within a field. The default is to double-up\nthe character, e.g. \"He said, \"\"Hi!\"\"\"\nAdd another possible value, \"double\", to explicitly indicate\nthe default case?", "file": "string (newlines removed)\nThe local filesystem path to a CSV data file.\n", "header": "CSV data\nSupplemental data for the table header, added independently of and\nbefore any `header-rows` from the main CSV data. Must use the\nsame CSV format as the main CSV data.\n", "header-rows": "integer\nThe number of rows of CSV data to use in the table header.\nDefaults to 0.\n", "keepspace": "flag (empty)\nTreat whitespace immediately following the delimiter as\nsignificant. The default is to ignore such whitespace.\n", "quote": "char\nA one-character string5 used to quote elements\ncontaining the delimiter or which start with the quote\ncharacter. Defaults to `\"` (quote). May be specified as a\nUnicode code point; see the [unicode](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#unicode) directive for syntax\ndetails.\n", "stub-columns": "integer\nThe number of table columns to use as stubs (row titles, on the\nleft). Defaults to 0.\n", "url": "string (whitespace removed)\nAn Internet URL reference to a CSV data file.\n", "widths": "integer [integer...] or \"auto\"\nA list of relative column widths.\nThe default is equal-width columns (100%/#columns).\n\n\"auto\" delegates the determination of column widths to the backend\n(LaTeX, the HTML browser, ...).\n", "width": "[length](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#length-units) or [percentage](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#percentage-units)\nSets the width of the table to the specified length or percentage\nof the line width. If omitted, the renderer determines the width\nof the table based on its contents or the column `widths`.\n" }, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table", "license": "https://docutils.sourceforge.io/docs/" }, "danger(docutils.parsers.rst.directives.admonitions.Danger)": { "is_markdown": true, "description": [ "## Specific Admonitions", "", "| | |", "|-|-|", "| Directive Types | \"attention\", \"caution\", \"danger\", \"error\", \"hint\",", "\"important\", \"note\", \"tip\", \"warning\", \"admonition\" |", "| Doctree Elements | attention, caution, danger, error, hint, important,", "note, tip, warning, [admonition](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#admonition), [title](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#title) |", "| Directive Arguments | None. |", "| Directive Options | [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33), [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) |", "| Directive Content | Interpreted as body elements. |", "", "Admonitions are specially marked \"topics\" that can appear anywhere an", "ordinary body element can. They contain arbitrary body elements.", "Typically, an admonition is rendered as an offset block in a document,", "sometimes outlined or shaded, with a title matching the admonition", "type. For example:", "", "```", ".. DANGER::", " Beware killer rabbits!", "```", "", "This directive might be rendered something like this:", "", "```", "+------------------------+", "| !DANGER! |", "| |", "| Beware killer rabbits! |", "+------------------------+", "```", "", "The following admonition directives have been implemented:", "- attention", "- caution", "- danger", "- error", "- hint", "- important", "- note", "- tip", "- warning", "", "Any text immediately following the directive indicator (on the same", "line and/or indented on following lines) is interpreted as a directive", "block and is parsed for normal body elements. For example, the", "following \"note\" admonition directive contains one paragraph and a", "bullet list consisting of two list items:", "", "```", ".. note:: This is a note admonition.", " This is the second line of the first paragraph.", "", " - The note contains all indented body elements", " following.", " - It includes this bullet list.", "```" ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#danger", "license": "https://docutils.sourceforge.io/docs/" }, "date(docutils.parsers.rst.directives.misc.Date)": { "is_markdown": true, "description": [ "## Date", "", "| | |", "|-|-|", "| Directive Type | \"date\" |", "| Doctree Element | Text |", "| Directive Arguments | One, optional (date format). |", "| Directive Options | None. |", "| Directive Content | None. |", "", "The \"date\" directive generates the current local date and inserts it", "into the document as text. This directive may be used in substitution", "definitions only.", "", "The optional directive content is interpreted as the desired date", "format, using the same codes as Python's [time.strftime()](https://docs.python.org/3/library/time.html#time.strftime) function. The", "default format is \"%Y-%m-%d\" (ISO 8601 date), but time fields can also", "be used. Examples:", "", "```", ".. |date| date::", ".. |time| date:: %H:%M", "", "Today's date is |date|.", "", "This document was generated on |date| at |time|.", "```" ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#date", "license": "https://docutils.sourceforge.io/docs/" }, "default-role(docutils.parsers.rst.directives.misc.DefaultRole)": { "is_markdown": true, "description": [ "## Setting the Default Interpreted Text Role", "", "| | |", "|-|-|", "| Directive Type | \"default-role\" |", "| Doctree Element | None; affects subsequent parsing. |", "| Directive Arguments | One, optional (new default role name). |", "| Directive Options | None. |", "| Directive Content | None. |", "", "The \"default-role\" directive sets the default interpreted text role,", "the role that is used for interpreted text without an explicit role.", "For example, after setting the default role like this:", "", "```", ".. default-role:: subscript", "```", "", "any subsequent use of implicit-role interpreted text in the document", "will use the \"subscript\" role:", "", "```", "An example of a `default` role.", "```", "", "This will be parsed into the following document tree fragment:", "", "```", "", " An example of a", " ", " default", " role.", "```", "", "Custom roles may be used (see the \"[role](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#role)\" directive above), but it", "must have been declared in a document before it can be set as the", "default role. See the [reStructuredText Interpreted Text Roles](https:/docutils.sourceforge.io/docs/ref/rst/roles.html)", "document for details of built-in roles.", "", "The directive may be used without an argument to restore the initial", "default interpreted text role, which is application-dependent. The", "initial default interpreted text role of the standard reStructuredText", "parser is \"title-reference\"." ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#default-role", "license": "https://docutils.sourceforge.io/docs/" }, "epigraph(docutils.parsers.rst.directives.body.Epigraph)": { "is_markdown": true, "description": [ "## Epigraph", "", "| | |", "|-|-|", "| Directive Type | \"epigraph\" |", "| Doctree Element | [block_quote](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#block-quote) |", "| Directive Arguments | None. |", "| Directive Options | None. |", "| Directive Content | Interpreted as the body of the block quote. |", "", "An epigraph is an apposite (suitable, apt, or pertinent) short", "inscription, often a quotation or poem, at the beginning of a document", "or section.", "", "The \"epigraph\" directive produces an \"epigraph\"-class block quote.", "For example, this input:", "", "```", ".. epigraph::", "", " No matter where you go, there you are.", "", " -- Buckaroo Banzai", "```", "", "becomes this document tree fragment:", "", "```", "", " ", " No matter where you go, there you are.", " ", " Buckaroo Banzai", "```" ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#epigraph", "license": "https://docutils.sourceforge.io/docs/" }, "error(docutils.parsers.rst.directives.admonitions.Error)": { "is_markdown": true, "description": [ "## Specific Admonitions", "", "| | |", "|-|-|", "| Directive Types | \"attention\", \"caution\", \"danger\", \"error\", \"hint\",", "\"important\", \"note\", \"tip\", \"warning\", \"admonition\" |", "| Doctree Elements | attention, caution, danger, error, hint, important,", "note, tip, warning, [admonition](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#admonition), [title](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#title) |", "| Directive Arguments | None. |", "| Directive Options | [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33), [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) |", "| Directive Content | Interpreted as body elements. |", "", "Admonitions are specially marked \"topics\" that can appear anywhere an", "ordinary body element can. They contain arbitrary body elements.", "Typically, an admonition is rendered as an offset block in a document,", "sometimes outlined or shaded, with a title matching the admonition", "type. For example:", "", "```", ".. DANGER::", " Beware killer rabbits!", "```", "", "This directive might be rendered something like this:", "", "```", "+------------------------+", "| !DANGER! |", "| |", "| Beware killer rabbits! |", "+------------------------+", "```", "", "The following admonition directives have been implemented:", "- attention", "- caution", "- danger", "- error", "- hint", "- important", "- note", "- tip", "- warning", "", "Any text immediately following the directive indicator (on the same", "line and/or indented on following lines) is interpreted as a directive", "block and is parsed for normal body elements. For example, the", "following \"note\" admonition directive contains one paragraph and a", "bullet list consisting of two list items:", "", "```", ".. note:: This is a note admonition.", " This is the second line of the first paragraph.", "", " - The note contains all indented body elements", " following.", " - It includes this bullet list.", "```" ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#error", "license": "https://docutils.sourceforge.io/docs/" }, "figure(docutils.parsers.rst.directives.images.Figure)": { "is_markdown": true, "description": [ "## Figure", "", "| | |", "|-|-|", "| Directive Type | \"figure\" |", "| Doctree Elements | [figure](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#figure), [image](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#image), [caption](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#caption), [legend](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#legend) |", "| Directive Arguments | One, required (image URI). |", "| Directive Options | Possible (see below). |", "| Directive Content | Interpreted as the figure caption and an optional", "legend. |", "", "A \"figure\" consists of [image](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#image) data (including [image options](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#image-options)), an optional", "caption (a single paragraph), and an optional legend (arbitrary body", "elements). For page-based output media, figures might float to a different", "position if this helps the page layout.", "", "```", ".. figure:: picture.png", " :scale: 50 %", " :alt: map to buried treasure", "", " This is the caption of the figure (a simple paragraph).", "", " The legend consists of all elements after the caption. In this", " case, the legend consists of this paragraph and the following", " table:", "", " +-----------------------+-----------------------+", " | Symbol | Meaning |", " +=======================+=======================+", " | .. image:: tent.png | Campground |", " +-----------------------+-----------------------+", " | .. image:: waves.png | Lake |", " +-----------------------+-----------------------+", " | .. image:: peak.png | Mountain |", " +-----------------------+-----------------------+", "```", "", "There must be blank lines before the caption paragraph and before the", "legend. To specify a legend without a caption, use an empty comment", "(\"..\") in place of the caption.", "", "The \"figure\" directive supports all of the options of the \"image\"", "directive (see [image options](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#image-options) above). These options (except", "\"align\") are passed on to the contained image.", "", "`align`: \"left\", \"center\", or \"right\"", "The horizontal alignment of the figure, allowing the image to", "float and have the text flow around it. The specific behavior", "depends upon the browser or rendering software used.", "", "In addition, the following options are recognized:", "", "`figwidth`: \"image\", [length](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#length-units), or [percentage](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#percentage-units) of current line width", "The width of the figure.", "Limits the horizontal space used by the figure.", "A special value of \"image\" is allowed, in which case the", "included image's actual width is used (requires the [Python Imaging", "Library](https://pypi.org/project/Pillow/)). If the image file is not found or the required software is", "unavailable, this option is ignored.", "", "Sets the \"width\" attribute of the \"figure\" doctree element.", "", "This option does not scale the included image; use the \"width\"", "[image](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#image) option for that.", "", "```", "+---------------------------+", "| figure |", "| |", "|<------ figwidth --------->|", "| |", "| +---------------------+ |", "| | image | |", "| | | |", "| |<--- width --------->| |", "| +---------------------+ |", "| |", "|The figure's caption should|", "|wrap at this width. |", "+---------------------------+", "```", "", "`figclass`: text", "Set a [\"classes\"](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#classes) attribute value on the figure element. See the", "[class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33) directive below." ], "options": { "align": "\"left\", \"center\", or \"right\"\nThe horizontal alignment of the figure, allowing the image to\nfloat and have the text flow around it. The specific behavior\ndepends upon the browser or rendering software used.\n", "figwidth": "\"image\", [length](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#length-units), or [percentage](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#percentage-units) of current line width\nThe width of the figure.\nLimits the horizontal space used by the figure.\nA special value of \"image\" is allowed, in which case the\nincluded image's actual width is used (requires the [Python Imaging\nLibrary](https://pypi.org/project/Pillow/)). If the image file is not found or the required software is\nunavailable, this option is ignored.\n\nSets the \"width\" attribute of the \"figure\" doctree element.\n\nThis option does not scale the included image; use the \"width\"\n[image](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#image) option for that.\n\n```\n+---------------------------+\n| figure |\n| |\n|<------ figwidth --------->|\n| |\n| +---------------------+ |\n| | image | |\n| | | |\n| |<--- width --------->| |\n| +---------------------+ |\n| |\n|The figure's caption should|\n|wrap at this width. |\n+---------------------------+\n```\n", "figclass": "text\nSet a [\"classes\"](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#classes) attribute value on the figure element. See the\n[class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33) directive below.\n" }, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure", "license": "https://docutils.sourceforge.io/docs/" }, "footer(docutils.parsers.rst.directives.parts.Footer)": { "is_markdown": true, "description": [ "## Document Header & Footer", "", "| | |", "|-|-|", "| Directive Types | \"header\" and \"footer\" |", "| Doctree Elements | [decoration](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#decoration), header, footer |", "| Directive Arguments | None. |", "| Directive Options | None. |", "| Directive Content | Interpreted as body elements. |", "", "The \"header\" and \"footer\" directives create document decorations,", "useful for page navigation, notes, time/datestamp, etc. For example:", "", "```", ".. header:: This space for rent.", "```", "", "This will add a paragraph to the document header, which will appear at", "the top of the generated web page or at the top of every printed page.", "", "These directives may be used multiple times, cumulatively. There is", "currently support for only one header and footer.", "", "While it is possible to use the \"header\" and \"footer\" directives to", "create navigational elements for web pages, you should be aware", "that Docutils is meant to be used for document processing, and", "that a navigation bar is not typically part of a document.", "", "Thus, you may soon find Docutils' abilities to be insufficient for", "these purposes. At that time, you should consider using a", "documentation generator like [Sphinx](http://sphinx-doc.org/) rather than the \"header\" and", "\"footer\" directives.", "", "In addition to the use of these directives to populate header and", "footer content, content may also be added automatically by the", "processing system. For example, if certain runtime settings are", "enabled, the document footer is populated with processing information", "such as a datestamp, a link to [the Docutils website](https://docutils.sourceforge.io), etc." ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#footer", "license": "https://docutils.sourceforge.io/docs/" }, "header(docutils.parsers.rst.directives.parts.Header)": { "is_markdown": true, "description": [ "## Document Header & Footer", "", "| | |", "|-|-|", "| Directive Types | \"header\" and \"footer\" |", "| Doctree Elements | [decoration](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#decoration), header, footer |", "| Directive Arguments | None. |", "| Directive Options | None. |", "| Directive Content | Interpreted as body elements. |", "", "The \"header\" and \"footer\" directives create document decorations,", "useful for page navigation, notes, time/datestamp, etc. For example:", "", "```", ".. header:: This space for rent.", "```", "", "This will add a paragraph to the document header, which will appear at", "the top of the generated web page or at the top of every printed page.", "", "These directives may be used multiple times, cumulatively. There is", "currently support for only one header and footer.", "", "While it is possible to use the \"header\" and \"footer\" directives to", "create navigational elements for web pages, you should be aware", "that Docutils is meant to be used for document processing, and", "that a navigation bar is not typically part of a document.", "", "Thus, you may soon find Docutils' abilities to be insufficient for", "these purposes. At that time, you should consider using a", "documentation generator like [Sphinx](http://sphinx-doc.org/) rather than the \"header\" and", "\"footer\" directives.", "", "In addition to the use of these directives to populate header and", "footer content, content may also be added automatically by the", "processing system. For example, if certain runtime settings are", "enabled, the document footer is populated with processing information", "such as a datestamp, a link to [the Docutils website](https://docutils.sourceforge.io), etc." ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#header", "license": "https://docutils.sourceforge.io/docs/" }, "highlights(docutils.parsers.rst.directives.body.Highlights)": { "is_markdown": true, "description": [ "## Highlights", "", "| | |", "|-|-|", "| Directive Type | \"highlights\" |", "| Doctree Element | [block_quote](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#block-quote) |", "| Directive Arguments | None. |", "| Directive Options | None. |", "| Directive Content | Interpreted as the body of the block quote. |", "", "Highlights summarize the main points of a document or section, often", "consisting of a list.", "", "The \"highlights\" directive produces a \"highlights\"-class block quote.", "See [Epigraph](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#epigraph) above for an analogous example." ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#highlights", "license": "https://docutils.sourceforge.io/docs/" }, "admonition(docutils.parsers.rst.directives.admonitions.Admonition)": { "is_markdown": true, "description": [ "## Generic Admonition", "", "| | |", "|-|-|", "| Directive Type | \"admonition\" |", "| Doctree Elements | [admonition](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#admonition), [title](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#title) |", "| Directive Arguments | One, required (admonition title) |", "| Directive Options | [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33), [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) |", "| Directive Content | Interpreted as body elements. |", "", "This is a generic, titled admonition. The title may be anything the", "author desires.", "", "The author-supplied title is also used as a [\"classes\"](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#classes) attribute value", "after being converted into a valid identifier form (down-cased;", "non-alphanumeric characters converted to single hyphens; \"admonition-\"", "prefixed). For example, this admonition:", "", "```", ".. admonition:: And, by the way...", "", " You can make up your own admonition too.", "```", "", "becomes the following document tree (pseudo-XML):", "", "```", "", " ", " ", " And, by the way...", " <paragraph>", " You can make up your own admonition too.", "```", "", "The [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33) option overrides the computed [\"classes\"](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#classes) attribute", "value." ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#generic-admonition", "license": "https://docutils.sourceforge.io/docs/" }, "hint(docutils.parsers.rst.directives.admonitions.Hint)": { "is_markdown": true, "description": [ "## Specific Admonitions", "", "| | |", "|-|-|", "| Directive Types | \"attention\", \"caution\", \"danger\", \"error\", \"hint\",", "\"important\", \"note\", \"tip\", \"warning\", \"admonition\" |", "| Doctree Elements | attention, caution, danger, error, hint, important,", "note, tip, warning, [admonition](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#admonition), [title](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#title) |", "| Directive Arguments | None. |", "| Directive Options | [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33), [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) |", "| Directive Content | Interpreted as body elements. |", "", "Admonitions are specially marked \"topics\" that can appear anywhere an", "ordinary body element can. They contain arbitrary body elements.", "Typically, an admonition is rendered as an offset block in a document,", "sometimes outlined or shaded, with a title matching the admonition", "type. For example:", "", "```", ".. DANGER::", " Beware killer rabbits!", "```", "", "This directive might be rendered something like this:", "", "```", "+------------------------+", "| !DANGER! |", "| |", "| Beware killer rabbits! |", "+------------------------+", "```", "", "The following admonition directives have been implemented:", "- attention", "- caution", "- danger", "- error", "- hint", "- important", "- note", "- tip", "- warning", "", "Any text immediately following the directive indicator (on the same", "line and/or indented on following lines) is interpreted as a directive", "block and is parsed for normal body elements. For example, the", "following \"note\" admonition directive contains one paragraph and a", "bullet list consisting of two list items:", "", "```", ".. note:: This is a note admonition.", " This is the second line of the first paragraph.", "", " - The note contains all indented body elements", " following.", " - It includes this bullet list.", "```" ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#hint", "license": "https://docutils.sourceforge.io/docs/" }, "image(docutils.parsers.rst.directives.images.Image)": { "is_markdown": true, "description": [ "## Image", "", "| | |", "|-|-|", "| Directive Type | \"image\" |", "| Doctree Element | [image](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#image) |", "| Directive Arguments | One, required (image URI). |", "| Directive Options | Possible (see below). |", "| Directive Content | None. |", "", "An \"image\" is a simple picture:", "", "```", ".. image:: picture.png", "```", "", "Inline images can be defined with an \"image\" directive in a [substitution", "definition](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions)", "", "The URI for the image source file is specified in the directive", "argument. As with hyperlink targets, the image URI may begin on the", "same line as the explicit markup start and target name, or it may", "begin in an indented text block immediately following, with no", "intervening blank lines. If there are multiple lines in the link", "block, they are stripped of leading and trailing whitespace and joined", "together.", "", "Optionally, the image link block may contain a flat field list, the", "image options. For example:", "", "```", ".. image:: picture.jpeg", " :height: 100px", " :width: 200 px", " :scale: 50 %", " :alt: alternate text", " :align: right", "```", "", "The following options are recognized:", "", "`alt`: text", "Alternate text: a short description of the image, displayed by", "applications that cannot display images, or spoken by applications", "for visually impaired users.", "", "`height`: [length](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#length-units)", "The desired height of the image.", "Used to reserve space or scale the image vertically. When the \"scale\"", "option is also specified, they are combined. For example, a height of", "200px and a scale of 50 is equivalent to a height of 100px with no scale.", "", "`width`: [length](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#length-units) or [percentage](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#percentage-units) of the current line width", "The width of the image.", "Used to reserve space or scale the image horizontally. As with \"height\"", "above, when the \"scale\" option is also specified, they are combined.", "", "`scale`: integer percentage (the \"%\" symbol is optional)", "The uniform scaling factor of the image. The default is \"100\u00a0%\", i.e.", "no scaling.", "", "If no \"height\" or \"width\" options are specified, the Python", "Imaging Library (PIL/[Pillow](https://pypi.org/project/Pillow/)) may be used to determine them, if", "it is installed and the image file is available.", "", "`align`: \"top\", \"middle\", \"bottom\", \"left\", \"center\", or \"right\"", "The alignment of the image, equivalent to the HTML `<img>` tag's", "deprecated \"align\" attribute or the corresponding \"vertical-align\" and", "\"text-align\" CSS properties.", "The values \"top\", \"middle\", and \"bottom\"", "control an image's vertical alignment (relative to the text", "baseline); they are only useful for inline images (substitutions).", "The values \"left\", \"center\", and \"right\" control an image's", "horizontal alignment, allowing the image to float and have the", "text flow around it. The specific behavior depends upon the", "browser or rendering software used.", "", "`target`: text (URI or reference name)", "Makes the image into a hyperlink reference (\"clickable\"). The", "option argument may be a URI (relative or absolute), or a", "[reference name](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#reference-names) with underscore suffix (e.g. ``a name`_`).", "", "and the common options [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33) and [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name)." ], "options": { "alt": "text\nAlternate text: a short description of the image, displayed by\napplications that cannot display images, or spoken by applications\nfor visually impaired users.\n", "height": "[length](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#length-units)\nThe desired height of the image.\nUsed to reserve space or scale the image vertically. When the \"scale\"\noption is also specified, they are combined. For example, a height of\n200px and a scale of 50 is equivalent to a height of 100px with no scale.\n", "width": "[length](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#length-units) or [percentage](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#percentage-units) of the current line width\nThe width of the image.\nUsed to reserve space or scale the image horizontally. As with \"height\"\nabove, when the \"scale\" option is also specified, they are combined.\n", "scale": "integer percentage (the \"%\" symbol is optional)\nThe uniform scaling factor of the image. The default is \"100\u00a0%\", i.e.\nno scaling.\n\nIf no \"height\" or \"width\" options are specified, the Python\nImaging Library (PIL/[Pillow](https://pypi.org/project/Pillow/)) may be used to determine them, if\nit is installed and the image file is available.\n", "align": "\"top\", \"middle\", \"bottom\", \"left\", \"center\", or \"right\"\nThe alignment of the image, equivalent to the HTML `<img>` tag's\ndeprecated \"align\" attribute or the corresponding \"vertical-align\" and\n\"text-align\" CSS properties.\nThe values \"top\", \"middle\", and \"bottom\"\ncontrol an image's vertical alignment (relative to the text\nbaseline); they are only useful for inline images (substitutions).\nThe values \"left\", \"center\", and \"right\" control an image's\nhorizontal alignment, allowing the image to float and have the\ntext flow around it. The specific behavior depends upon the\nbrowser or rendering software used.\n", "target": "text (URI or reference name)\nMakes the image into a hyperlink reference (\"clickable\"). The\noption argument may be a URI (relative or absolute), or a\n[reference name](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#reference-names) with underscore suffix (e.g. ``a name`_`).\n" }, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#image", "license": "https://docutils.sourceforge.io/docs/" }, "important(docutils.parsers.rst.directives.admonitions.Important)": { "is_markdown": true, "description": [ "## Specific Admonitions", "", "| | |", "|-|-|", "| Directive Types | \"attention\", \"caution\", \"danger\", \"error\", \"hint\",", "\"important\", \"note\", \"tip\", \"warning\", \"admonition\" |", "| Doctree Elements | attention, caution, danger, error, hint, important,", "note, tip, warning, [admonition](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#admonition), [title](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#title) |", "| Directive Arguments | None. |", "| Directive Options | [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33), [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) |", "| Directive Content | Interpreted as body elements. |", "", "Admonitions are specially marked \"topics\" that can appear anywhere an", "ordinary body element can. They contain arbitrary body elements.", "Typically, an admonition is rendered as an offset block in a document,", "sometimes outlined or shaded, with a title matching the admonition", "type. For example:", "", "```", ".. DANGER::", " Beware killer rabbits!", "```", "", "This directive might be rendered something like this:", "", "```", "+------------------------+", "| !DANGER! |", "| |", "| Beware killer rabbits! |", "+------------------------+", "```", "", "The following admonition directives have been implemented:", "- attention", "- caution", "- danger", "- error", "- hint", "- important", "- note", "- tip", "- warning", "", "Any text immediately following the directive indicator (on the same", "line and/or indented on following lines) is interpreted as a directive", "block and is parsed for normal body elements. For example, the", "following \"note\" admonition directive contains one paragraph and a", "bullet list consisting of two list items:", "", "```", ".. note:: This is a note admonition.", " This is the second line of the first paragraph.", "", " - The note contains all indented body elements", " following.", " - It includes this bullet list.", "```" ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#important", "license": "https://docutils.sourceforge.io/docs/" }, "include(docutils.parsers.rst.directives.misc.Include)": { "is_markdown": true, "description": [ "## Including an External Document Fragment", "", "| | |", "|-|-|", "| Directive Type | \"include\" |", "| Doctree Elements | Depend on data being included", "([literal_block](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#literal-block) with `code` or `literal` option). |", "| Directive Arguments | One, required (path to the file to include). |", "| Directive Options | Possible (see below). |", "| Directive Content | None. |", "| Configuration Setting | [file_insertion_enabled](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#file-insertion-enabled) |", "", "The \"include\" directive represents a potential security hole. It", "can be disabled with the \"[file_insertion_enabled](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#file-insertion-enabled)\" runtime setting.", "", "The \"include\" directive reads a text file. The directive argument is", "the path to the file to be included, relative to the document containing", "the directive. Unless the options `literal`, `code`, or `parser`", "are given, the file is parsed in the current document's context at the", "point of the directive. For example:", "", "```", "This first example will be parsed at the document level, and can", "thus contain any construct, including section headers.", "", ".. include:: inclusion.txt", "", "Back in the main document.", "", " This second example will be parsed in a block quote context.", " Therefore it may only contain body elements. It may not", " contain section headers.", "", " .. include:: inclusion.txt", "```", "", "If an included document fragment contains section structure, the title", "adornments must match those of the master document.", "", "Standard data files intended for inclusion in reStructuredText", "documents are distributed with the Docutils source code, located in", "the \"docutils\" package in the `docutils/parsers/rst/include`", "directory. To access these files, use the special syntax for standard", "\"include\" data files, angle brackets around the file name:", "", "```", ".. include:: <isonum.txt>", "```", "", "The current set of standard \"include\" data files consists of sets of", "substitution definitions. See [reStructuredText Standard Definition", "Files](https:/docutils.sourceforge.io/docs/ref/rst/definitions.html) for details.", "", "The following options are recognized:", "", "`start-line`: integer", "Only the content starting from this line will be included.", "(As usual in Python, the first line has index 0 and negative values", "count from the end.)", "", "`end-line`: integer", "Only the content up to (but excluding) this line will be included.", "", "`start-after`: text to find in the external data file", "Only the content after the first occurrence of the specified text", "will be included.", "", "`end-before`: text to find in the external data file", "Only the content before the first occurrence of the specified text", "(but after any `after` text) will be included.", "", "`parser`: parser name", "Parse the included content with the specified parser.", "(New in Docutils 0.17)", "", "`literal`: flag (empty)", "The entire included text is inserted into the document as a single", "literal block.", "", "`code`: [string] (formal language)", "The argument and the included content are passed to", "the [code](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#code) directive (useful for program listings).", "", "`number-lines`: [integer] (start line number)", "Precede every code line with a line number.", "The optional argument is the number of the first line (default 1).", "Works only with `code` or `literal`.", "", "`encoding`: string", "The text encoding of the external data file. Defaults to the", "document's [input_encoding](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#input-encoding).", "", "`tab-width`: integer", "Number of spaces for hard tab expansion.", "A negative value prevents expansion of hard tabs. Defaults to the", "[tab_width](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#tab-width) configuration setting.", "", "With `code` or `literal` the common options [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33) and", "[name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) are recognized as well.", "", "Combining `start/end-line` and `start-after/end-before` is possible. The", "text markers will be searched in the specified lines (further limiting the", "included content)." ], "options": { "start-line": "integer\nOnly the content starting from this line will be included.\n(As usual in Python, the first line has index 0 and negative values\ncount from the end.)\n", "end-line": "integer\nOnly the content up to (but excluding) this line will be included.\n", "start-after": "text to find in the external data file\nOnly the content after the first occurrence of the specified text\nwill be included.\n", "end-before": "text to find in the external data file\nOnly the content before the first occurrence of the specified text\n(but after any `after` text) will be included.\n", "parser": "parser name\nParse the included content with the specified parser.\n(New in Docutils 0.17)\n", "literal": "flag (empty)\nThe entire included text is inserted into the document as a single\nliteral block.\n", "code": "[string] (formal language)\nThe argument and the included content are passed to\nthe [code](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#code) directive (useful for program listings).\n", "number-lines": "[integer] (start line number)\nPrecede every code line with a line number.\nThe optional argument is the number of the first line (default 1).\nWorks only with `code` or `literal`.\n", "encoding": "string\nThe text encoding of the external data file. Defaults to the\ndocument's [input_encoding](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#input-encoding).\n", "tab-width": "integer\nNumber of spaces for hard tab expansion.\nA negative value prevents expansion of hard tabs. Defaults to the\n[tab_width](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#tab-width) configuration setting.\n" }, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#include", "license": "https://docutils.sourceforge.io/docs/" }, "line-block(docutils.parsers.rst.directives.body.LineBlock)": { "is_markdown": true, "description": [ "## Line Block", "## Deprecated", "", "The \"line-block\" directive is deprecated. Use the [line block", "syntax](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks) instead.", "", "| | |", "|-|-|", "| Directive Type | \"line-block\" |", "| Doctree Element | [line_block](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#line-block) |", "| Directive Arguments | None. |", "| Directive Options | [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33), [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) |", "| Directive Content | Becomes the body of the line block. |", "", "The \"line-block\" directive constructs an element where line breaks and", "initial indentation is significant and inline markup is supported. It", "is equivalent to a [parsed literal block](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#parsed-literal-block) with different rendering:", "typically in an ordinary serif typeface instead of a", "typewriter/monospaced face, and not automatically indented. (Have the", "line-block directive begin a block quote to get an indented line", "block.) Line blocks are useful for address blocks and verse (poetry,", "song lyrics), where the structure of lines is significant. For", "example, here's a classic:", "", "```", "\"To Ma Own Beloved Lassie: A Poem on her 17th Birthday\", by", "Ewan McTeagle (for Lassie O'Shea):", "", " .. line-block::", "", " Lend us a couple of bob till Thursday.", " I'm absolutely skint.", " But I'm expecting a postal order and I can pay you back", " as soon as it comes.", " Love, Ewan.", "```" ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#line-block", "license": "https://docutils.sourceforge.io/docs/" }, "list-table(docutils.parsers.rst.directives.tables.ListTable)": { "is_markdown": true, "description": [ "## List Table", "", "| | |", "|-|-|", "| Directive Type | \"list-table\" |", "| Doctree Element | [table](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#table) |", "| Directive Arguments | One, optional (table title). |", "| Directive Options | Possible (see below). |", "| Directive Content | A uniform two-level bullet list. |", "", "(This is an initial implementation; [further ideas](https:/docutils.sourceforge.io/docs/ref/rst/../../dev/rst/alternatives.html#list-driven-tables) may be implemented", "in the future.)", "", "The \"list-table\" directive is used to create a table from data in a", "uniform two-level bullet list. \"Uniform\" means that each sublist", "(second-level list) must contain the same number of list items.", "", "Example:", "", "```", ".. list-table:: Frozen Delights!", " :widths: 15 10 30", " :header-rows: 1", "", " * - Treat", " - Quantity", " - Description", " * - Albatross", " - 2.99", " - On a stick!", " * - Crunchy Frog", " - 1.49", " - If we took the bones out, it wouldn't be", " crunchy, now would it?", " * - Gannet Ripple", " - 1.99", " - On a stick!", "```", "", "The following options are recognized:", "", "`align`: \"left\", \"center\", or \"right\"", "The horizontal alignment of the table.", "(New in Docutils 0.13)", "", "`header-rows`: integer", "The number of rows of list data to use in the table header.", "Defaults to 0.", "", "`stub-columns`: integer", "The number of table columns to use as stubs (row titles, on the", "left). Defaults to 0.", "", "`width`: [length](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#length-units) or [percentage](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#percentage-units)", "Sets the width of the table to the specified length or percentage", "of the line width. If omitted, the renderer determines the width", "of the table based on its contents or the column `widths`.", "", "`widths`: integer [integer...] or \"auto\"", "A list of relative column widths.", "The default is equal-width columns (100%/#columns).", "", "\"auto\" delegates the determination of column widths to the backend", "(LaTeX, the HTML browser, ...).", "", "and the common options [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33) and [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name)." ], "options": { "align": "\"left\", \"center\", or \"right\"\nThe horizontal alignment of the table.\n(New in Docutils 0.13)\n", "header-rows": "integer\nThe number of rows of list data to use in the table header.\nDefaults to 0.\n", "stub-columns": "integer\nThe number of table columns to use as stubs (row titles, on the\nleft). Defaults to 0.\n", "width": "[length](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#length-units) or [percentage](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#percentage-units)\nSets the width of the table to the specified length or percentage\nof the line width. If omitted, the renderer determines the width\nof the table based on its contents or the column `widths`.\n", "widths": "integer [integer...] or \"auto\"\nA list of relative column widths.\nThe default is equal-width columns (100%/#columns).\n\n\"auto\" delegates the determination of column widths to the backend\n(LaTeX, the HTML browser, ...).\n" }, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table", "license": "https://docutils.sourceforge.io/docs/" }, "math(docutils.parsers.rst.directives.body.MathBlock)": { "is_markdown": true, "description": [ "## Math", "", "| | |", "|-|-|", "| Directive Type | \"math\" |", "| Doctree Element | [math_block](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#math-block) |", "| Directive Arguments | None. |", "| Directive Options | [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33), [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) |", "| Directive Content | Becomes the body of the math block.", "(Content blocks separated by a blank line are put in", "adjacent math blocks.) |", "| Configuration Setting | [math_output](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#math-output) |", "", "The \"math\" directive inserts blocks with mathematical content", "(display formulas, equations) into the document. The input format is", "[LaTeX math syntax](https:/docutils.sourceforge.io/docs/ref/rst/../../ref/rst/mathematics.html) with support for Unicode symbols, for example:", "", "```", ".. math::", "", " \u03b1_t(i) = P(O_1, O_2, \u2026 O_t, q_t = S_i \u03bb)", "```", "", "Support is limited to a subset of LaTeX math by the conversion", "required for many output formats. For HTML, the [math_output](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#math-output)", "configuration setting (or the corresponding `--math-output`", "command line option) select between alternative output formats with", "different subsets of supported elements. If a writer does not", "support math typesetting, the content is inserted verbatim.", "", "For inline formulas, use the [\"math\" role](https:/docutils.sourceforge.io/docs/ref/rst/roles.html#math)." ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#math", "license": "https://docutils.sourceforge.io/docs/" }, "meta(docutils.parsers.rst.directives.html.Meta)": { "is_markdown": true, "description": [ "## Metadata", "", "| | |", "|-|-|", "| Directive Type | \"meta\" |", "| Doctree Element | [meta](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#meta) |", "| Directive Arguments | None. |", "| Directive Options | None. |", "| Directive Content | Must contain a flat field list. |", "", "The \"meta\" directive is used to specify metadata9 to be stored", "in, e.g., [HTML meta elements](https://html.spec.whatwg.org/multipage/semantics.html#the-meta-element) or as [ODT file properties](https://en.wikipedia.org/wiki/OpenDocument_technical_specification#Metadata). The", "LaTeX writer passes it to the `pdfinfo` option of the [hyperref](https://ctan.org/pkg/hyperref)", "package. If an output format does not support \"invisible\" metadata,", "content is silently dropped by the writer.", "", "Data from some [bibliographic fields](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bibliographic-fields) is automatically", "extracted and stored as metadata, too. However, Bibliographic", "Fields are also displayed in the document's screen rendering or", "printout.", "", "For an \"invisible\" document title, see the [metadata document", "title](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#metadata-document-title) directive below.", "", "Within the directive block, a flat field list provides the syntax for", "metadata. The field name becomes the contents of the \"name\" attribute", "of the META tag, and the field body (interpreted as a single string", "without inline markup) becomes the contents of the \"content\"", "attribute. For example:", "", "```", ".. meta::", " :description: The reStructuredText plaintext markup language", " :keywords: plaintext, markup language", "```", "", "This would be converted to the following HTML:", "", "```", "<meta name=\"description\"", " content=\"The reStructuredText plaintext markup language\">", "<meta name=\"keywords\" content=\"plaintext, markup language\">", "```", "", "Support for other META attributes (\"http-equiv\", \"scheme\", \"lang\",", "\"dir\") are provided through field arguments, which must be of the form", "\"attr=value\":", "", "```", ".. meta::", " :description lang=en: An amusing story", " :description lang=fr: Une histoire amusante", "```", "", "And their HTML equivalents:", "", "```", "<meta name=\"description\" lang=\"en\" content=\"An amusing story\">", "<meta name=\"description\" lang=\"fr\" content=\"Une histoire amusante\">", "```", "", "Some META tags use an \"http-equiv\" attribute instead of the \"name\"", "attribute. To specify \"http-equiv\" META tags, simply omit the name:", "", "```", ".. meta::", " :http-equiv=Content-Type: text/html; charset=ISO-8859-1", "```", "", "HTML equivalent:", "", "```", "<meta http-equiv=\"Content-Type\"", " content=\"text/html; charset=ISO-8859-1\">", "```", "9", "\"Metadata\" is data about data, in this case data about the", "document. Metadata is, e.g., used to describe and classify web", "pages in the World Wide Web, in a form that is easy for search", "engines to extract and collate." ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata", "license": "https://docutils.sourceforge.io/docs/" }, "title(docutils.parsers.rst.directives.misc.Title)": { "is_markdown": true, "description": [ "## Metadata Document Title", "", "| | |", "|-|-|", "| Directive Type | \"title\" |", "| Doctree Element | Sets the document's [title attribute](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#title-attribute). |", "| Directive Arguments | One, required (the title text). |", "| Directive Options | None. |", "| Directive Content | None. |", "", "The \"title\" directive specifies the document title as metadata, which", "does not become part of the document body. It overrides the", "document-supplied [document title](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#document-title) and the [\"title\" configuration", "setting](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#title). For example, in HTML output the metadata document title", "appears in the title bar of the browser window." ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata-document-title", "license": "https://docutils.sourceforge.io/docs/" }, "note(docutils.parsers.rst.directives.admonitions.Note)": { "is_markdown": true, "description": [ "## Specific Admonitions", "", "| | |", "|-|-|", "| Directive Types | \"attention\", \"caution\", \"danger\", \"error\", \"hint\",", "\"important\", \"note\", \"tip\", \"warning\", \"admonition\" |", "| Doctree Elements | attention, caution, danger, error, hint, important,", "note, tip, warning, [admonition](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#admonition), [title](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#title) |", "| Directive Arguments | None. |", "| Directive Options | [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33), [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) |", "| Directive Content | Interpreted as body elements. |", "", "Admonitions are specially marked \"topics\" that can appear anywhere an", "ordinary body element can. They contain arbitrary body elements.", "Typically, an admonition is rendered as an offset block in a document,", "sometimes outlined or shaded, with a title matching the admonition", "type. For example:", "", "```", ".. DANGER::", " Beware killer rabbits!", "```", "", "This directive might be rendered something like this:", "", "```", "+------------------------+", "| !DANGER! |", "| |", "| Beware killer rabbits! |", "+------------------------+", "```", "", "The following admonition directives have been implemented:", "- attention", "- caution", "- danger", "- error", "- hint", "- important", "- note", "- tip", "- warning", "", "Any text immediately following the directive indicator (on the same", "line and/or indented on following lines) is interpreted as a directive", "block and is parsed for normal body elements. For example, the", "following \"note\" admonition directive contains one paragraph and a", "bullet list consisting of two list items:", "", "```", ".. note:: This is a note admonition.", " This is the second line of the first paragraph.", "", " - The note contains all indented body elements", " following.", " - It includes this bullet list.", "```" ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#note", "license": "https://docutils.sourceforge.io/docs/" }, "parsed-literal(docutils.parsers.rst.directives.body.ParsedLiteral)": { "is_markdown": true, "description": [ "## Parsed Literal Block", "", "| | |", "|-|-|", "| Directive Type | \"parsed-literal\" |", "| Doctree Element | [literal_block](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#literal-block) |", "| Directive Arguments | None. |", "| Directive Options | [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33), [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) |", "| Directive Content | Becomes the body of the literal block. |", "", "Unlike an ordinary literal block, the \"parsed-literal\" directive", "constructs a literal block where the text is parsed for inline markup.", "It is equivalent to a [line block](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#line-block) with different rendering:", "typically in a typewriter/monospaced typeface, like an ordinary", "literal block. Parsed literal blocks are useful for adding hyperlinks", "to code examples.", "", "However, care must be taken with the text, because inline markup is", "recognized and there is no protection from parsing. Backslash-escapes", "may be necessary to prevent unintended parsing. And because the", "markup characters are removed by the parser, care must also be taken", "with vertical alignment. Parsed \"ASCII art\" is tricky, and extra", "whitespace may be necessary.", "", "For example, all the element names in this content model are links:", "", "```", ".. parsed-literal::", "", " ( (title_, subtitle_?)?,", " decoration_?,", " (docinfo_, transition_?)?,", " `%structure.model;`_ )", "```" ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal", "license": "https://docutils.sourceforge.io/docs/" }, "pull-quote(docutils.parsers.rst.directives.body.PullQuote)": { "is_markdown": true, "description": [ "## Pull-Quote", "", "| | |", "|-|-|", "| Directive Type | \"pull-quote\" |", "| Doctree Element | [block_quote](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#block-quote) |", "| Directive Arguments | None. |", "| Directive Options | None. |", "| Directive Content | Interpreted as the body of the block quote. |", "", "A pull-quote is a small selection of text \"pulled out and quoted\",", "typically in a larger typeface. Pull-quotes are used to attract", "attention, especially in long articles.", "", "The \"pull-quote\" directive produces a \"pull-quote\"-class block quote.", "See [Epigraph](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#epigraph) above for an analogous example." ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#pull-quote", "license": "https://docutils.sourceforge.io/docs/" }, "raw(docutils.parsers.rst.directives.misc.Raw)": { "is_markdown": true, "description": [ "## Raw Data Pass-Through", "", "| | |", "|-|-|", "| Directive Type | \"raw\" |", "| Doctree Element | [raw](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#raw) |", "| Directive Arguments | One or more, required (output format types). |", "| Directive Options | Possible (see below). |", "| Directive Content | Stored verbatim, uninterpreted. None (empty) if a", "\"file\" or \"url\" option given. |", "| Configuration Setting | [raw_enabled](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#raw-enabled) |", "", "The \"raw\" directive represents a potential security hole. It can", "be disabled with the \"[raw_enabled](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#raw-enabled)\" or \"[file_insertion_enabled](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#file-insertion-enabled)\"", "runtime settings.", "", "The \"raw\" directive is a stop-gap measure allowing the author to", "bypass reStructuredText's markup. It is a \"power-user\" feature", "that should not be overused or abused. The use of \"raw\" ties", "documents to specific output formats and makes them less portable.", "", "If you often need to use the \"raw\" directive or a \"raw\"-derived", "interpreted text role, that is a sign either of overuse/abuse or", "that functionality may be missing from reStructuredText. Please", "describe your situation in a message to the [Docutils-users](https:/docutils.sourceforge.io/docs/ref/rst/../../user/mailing-lists.html#docutils-users) mailing", "list.", "", "The \"raw\" directive indicates non-reStructuredText data that is to be", "passed untouched to the Writer. The names of the output formats are", "given in the directive arguments. The interpretation of the raw data", "is up to the Writer. A Writer may ignore any raw output not matching", "its format.", "", "For example, the following input would be passed untouched by an HTML", "Writer:", "", "```", ".. raw:: html", "", " <hr width=50 size=10>", "```", "", "A LaTeX Writer could insert the following raw content into its", "output stream:", "", "```", ".. raw:: latex", "", " \\setlength{\\parindent}{0pt}", "```", "", "Raw data can also be read from an external file, specified in a", "directive option. In this case, the content block must be empty. For", "example:", "", "```", ".. raw:: html", " :file: inclusion.html", "```", "", "Inline equivalents of the \"raw\" directive can be defined via", "[custom interpreted text roles](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#custom-interpreted-text-roles) derived from the [\"raw\" role](https:/docutils.sourceforge.io/docs/ref/rst/roles.html#raw).", "", "The following options are recognized:", "", "`file`: string (newlines removed)", "The local filesystem path of a raw data file to be included.", "", "`url`: string (whitespace removed)", "An Internet URL reference to a raw data file to be included.", "", "`encoding`: string", "The text encoding of the external raw data (file or URL).", "Defaults to the document's encoding (if specified).", "", "and the common option [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33)." ], "options": { "file": "string (newlines removed)\nThe local filesystem path of a raw data file to be included.\n", "url": "string (whitespace removed)\nAn Internet URL reference to a raw data file to be included.\n", "encoding": "string\nThe text encoding of the external raw data (file or URL).\nDefaults to the document's encoding (if specified).\n" }, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw-directive", "license": "https://docutils.sourceforge.io/docs/" }, "replace(docutils.parsers.rst.directives.misc.Replace)": { "is_markdown": true, "description": [ "## Replacement Text", "", "| | |", "|-|-|", "| Directive Type | \"replace\" |", "| Doctree Element | Text & [inline elements](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#inline-elements) |", "| Directive Arguments | None. |", "| Directive Options | None. |", "| Directive Content | A single paragraph; may contain inline markup. |", "", "The \"replace\" directive is used to indicate replacement text for a", "substitution reference. It may be used within [substitution", "definitions](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions) only. For example, this directive can be used to expand", "abbreviations:", "", "```", ".. |reST| replace:: reStructuredText", "", "Yes, |reST| is a long word, so I can't blame anyone for wanting to", "abbreviate it.", "```", "", "As reStructuredText doesn't support nested inline markup, the only way", "to create a reference with styled text is to use substitutions with", "the \"replace\" directive:", "", "```", "I recommend you try |Python|_.", "", ".. |Python| replace:: Python, *the* best language around", ".. _Python: https://www.python.org/", "```" ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#replace", "license": "https://docutils.sourceforge.io/docs/" }, "role(docutils.parsers.rst.directives.misc.Role)": { "is_markdown": true, "description": [ "## Custom Interpreted Text Roles", "", "| | |", "|-|-|", "| Directive Type | \"role\" |", "| Doctree Element | None; affects subsequent parsing. |", "| Directive Arguments | Two; one required (new [role name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#role-name)), one optional", "(base role name, in parentheses). |", "| Directive Options | Possible (depends on base role). |", "| Directive Content | depends on base role. |", "", "The \"role\" directive dynamically creates a custom [interpreted text", "role](https:/docutils.sourceforge.io/docs/ref/rst/roles.html) and registers it with the parser. This means that after", "declaring a role like this:", "", "```", ".. role:: custom", "```", "", "the document may use the new \"custom\" role:", "", "```", "An example of using :custom:`interpreted text`", "```", "", "This will be parsed into the following document tree fragment:", "", "```", "<paragraph>", " An example of using", " <inline classes=\"custom\">", " interpreted text", "```", "", "The role must be declared in a document before it can be used.", "", "Role names are case insensitive and must conform to the rules of", "simple [reference names](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#reference-names) (but do not share a namespace with", "hyperlinks, footnotes, and citations).", "", "The new role may be based on an existing role, specified as a second", "argument in parentheses (whitespace optional):", "", "```", ".. role:: custom(emphasis)", "", ":custom:`text`", "```", "", "The parsed result is as follows:", "", "```", "<paragraph>", " <emphasis classes=\"custom\">", " text", "```", "", "A special case is the [\"raw\" role](https:/docutils.sourceforge.io/docs/ref/rst/roles.html#raw): derived roles enable", "inline [raw data pass-through](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#raw-data-pass-through), e.g.:", "", "```", ".. role:: raw-role(raw)", " :format: html latex", "", ":raw-role:`raw text`", "```", "", "If no base role is explicitly specified, a generic custom role is", "automatically used. Subsequent interpreted text will produce an", "\"inline\" element with a [\"classes\"](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#classes) attribute, as in the first example", "above.", "", "With most roles, the \":class:\" option can be used to set a \"classes\"", "attribute that is different from the role name. For example:", "", "```", ".. role:: custom", " :class: special", "", ":custom:`interpreted text`", "```", "", "This is the parsed result:", "", "```", "<paragraph>", " <inline classes=\"special\">", " interpreted text", "```", "", "The following option is recognized by the \"role\" directive for most", "base roles:", "", "`class`: text", "Set the [\"classes\"](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#classes) attribute value on the element produced", "(`inline`, or element associated with a base class) when the", "custom interpreted text role is used. If no directive options are", "specified, a \"class\" option with the directive argument (role", "name) as the value is implied. See the [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33) directive above.", "", "Specific base roles may support other options and/or directive", "content. See the [reStructuredText Interpreted Text Roles](https:/docutils.sourceforge.io/docs/ref/rst/roles.html) document", "for details." ], "options": { "class": "text\nSet the [\"classes\"](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#classes) attribute value on the element produced\n(`inline`, or element associated with a base class) when the\ncustom interpreted text role is used. If no directive options are\nspecified, a \"class\" option with the directive argument (role\nname) as the value is implied. See the [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33) directive above.\n" }, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#role", "license": "https://docutils.sourceforge.io/docs/" }, "rubric(docutils.parsers.rst.directives.body.Rubric)": { "is_markdown": true, "description": [ "## Rubric", "", "| | |", "|-|-|", "| Directive Type | \"rubric\" |", "| Doctree Element | [rubric](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#rubric) |", "| Directive Arguments | One, required (rubric text). |", "| Directive Options | [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33), [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) |", "| Directive Content | None. |", "", "rubric n. 1. a title, heading, or the like, in a manuscript,", "book, statute, etc., written or printed in red or otherwise", "distinguished from the rest of the text. ...", "Random House Webster's College Dictionary, 1991", "The \"rubric\" directive inserts a \"rubric\" element into the document", "tree. A rubric is like an informal heading that doesn't correspond to", "the document's structure." ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#rubric", "license": "https://docutils.sourceforge.io/docs/" }, "sidebar(docutils.parsers.rst.directives.body.Sidebar)": { "is_markdown": true, "description": [ "## Sidebar", "", "| | |", "|-|-|", "| Directive Type | \"sidebar\" |", "| Doctree Element | [sidebar](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#sidebar) |", "| Directive Arguments | One, optional (sidebar title). |", "| Directive Options | Possible (see below). |", "| Directive Content | Interpreted as the sidebar body. |", "", "Sidebars are like miniature, parallel documents that occur inside", "other documents, providing related or reference material. A sidebar", "is typically offset by a border and \"floats\" to the side of the page;", "the document's main text may flow around it. Sidebars can also be", "likened to super-footnotes; their content is outside of the flow of", "the document's main text.", "", "Sidebars may occur anywhere a section or transition may occur. Body", "elements (including sidebars) may not contain nested sidebars.", "", "The directive's sole argument is interpreted as the sidebar title,", "which may be followed by a subtitle option (see below); the next line", "must be blank. All subsequent lines make up the sidebar body,", "interpreted as body elements. For example:", "", "```", ".. sidebar:: Optional Sidebar Title", " :subtitle: Optional Sidebar Subtitle", "", " Subsequent indented lines comprise", " the body of the sidebar, and are", " interpreted as body elements.", "```", "", "The following options are recognized:", "", "`subtitle`: text", "The sidebar's subtitle.", "", "and the common options [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33) and [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name)." ], "options": { "subtitle": "text\nThe sidebar's subtitle.\n" }, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#sidebar", "license": "https://docutils.sourceforge.io/docs/" }, "table(docutils.parsers.rst.directives.tables.RSTTable)": { "is_markdown": true, "description": [ "## Table", "", "| | |", "|-|-|", "| Directive Type | \"table\" |", "| Doctree Element | [table](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#table) |", "| Directive Arguments | One, optional (table title). |", "| Directive Options | Possible (see below). |", "| Directive Content | A normal [reStructuredText table](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#tables). |", "", "The \"table\" directive is used to associate a", "title with a table or specify options, e.g.:", "", "```", ".. table:: Truth table for \"not\"", " :widths: auto", "", " ===== =====", " A not A", " ===== =====", " False True", " True False", " ===== =====", "```", "", "The following options are recognized:", "", "`align`: \"left\", \"center\", or \"right\"", "The horizontal alignment of the table (new in Docutils 0.13).", "", "`width`: [length](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#length-units) or [percentage](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#percentage-units)", "Sets the width of the table to the specified length or percentage", "of the line width. If omitted, the renderer determines the width", "of the table based on its contents or the column `widths`.", "", "`widths`: \"auto\", \"grid\", or a list of integers", "A list of relative column widths.", "The default is the width of the input columns (in characters).", "", "\"auto\" delegates the determination of column widths to the backend", "(LaTeX, the HTML browser, ...).", "", "\"grid\" restores the default, overriding a [table_style](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#table-style) or class", "value \"colwidths-auto\".", "", "Plus the common options [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33) and [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name)." ], "options": { "align": "\"left\", \"center\", or \"right\"\nThe horizontal alignment of the table (new in Docutils 0.13).\n", "width": "[length](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#length-units) or [percentage](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#percentage-units)\nSets the width of the table to the specified length or percentage\nof the line width. If omitted, the renderer determines the width\nof the table based on its contents or the column `widths`.\n", "widths": "\"auto\", \"grid\", or a list of integers\nA list of relative column widths.\nThe default is the width of the input columns (in characters).\n\n\"auto\" delegates the determination of column widths to the backend\n(LaTeX, the HTML browser, ...).\n\n\"grid\" restores the default, overriding a [table_style](https:/docutils.sourceforge.io/docs/ref/rst/../../user/config.html#table-style) or class\nvalue \"colwidths-auto\".\n" }, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#table", "license": "https://docutils.sourceforge.io/docs/" }, "tip(docutils.parsers.rst.directives.admonitions.Tip)": { "is_markdown": true, "description": [ "## Specific Admonitions", "", "| | |", "|-|-|", "| Directive Types | \"attention\", \"caution\", \"danger\", \"error\", \"hint\",", "\"important\", \"note\", \"tip\", \"warning\", \"admonition\" |", "| Doctree Elements | attention, caution, danger, error, hint, important,", "note, tip, warning, [admonition](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#admonition), [title](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#title) |", "| Directive Arguments | None. |", "| Directive Options | [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33), [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) |", "| Directive Content | Interpreted as body elements. |", "", "Admonitions are specially marked \"topics\" that can appear anywhere an", "ordinary body element can. They contain arbitrary body elements.", "Typically, an admonition is rendered as an offset block in a document,", "sometimes outlined or shaded, with a title matching the admonition", "type. For example:", "", "```", ".. DANGER::", " Beware killer rabbits!", "```", "", "This directive might be rendered something like this:", "", "```", "+------------------------+", "| !DANGER! |", "| |", "| Beware killer rabbits! |", "+------------------------+", "```", "", "The following admonition directives have been implemented:", "- attention", "- caution", "- danger", "- error", "- hint", "- important", "- note", "- tip", "- warning", "", "Any text immediately following the directive indicator (on the same", "line and/or indented on following lines) is interpreted as a directive", "block and is parsed for normal body elements. For example, the", "following \"note\" admonition directive contains one paragraph and a", "bullet list consisting of two list items:", "", "```", ".. note:: This is a note admonition.", " This is the second line of the first paragraph.", "", " - The note contains all indented body elements", " following.", " - It includes this bullet list.", "```" ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#tip", "license": "https://docutils.sourceforge.io/docs/" }, "topic(docutils.parsers.rst.directives.body.Topic)": { "is_markdown": true, "description": [ "## Topic", "", "| | |", "|-|-|", "| Directive Type | \"topic\" |", "| Doctree Element | [topic](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#topic) |", "| Directive Arguments | One, required (topic title). |", "| Directive Options | [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33), [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) |", "| Directive Content | Interpreted as the topic body. |", "", "A topic is like a block quote with a title, or a self-contained", "section with no subsections. Use the \"topic\" directive to indicate a", "self-contained idea that is separate from the flow of the document.", "Topics may occur anywhere a section or transition may occur. Body", "elements and topics may not contain nested topics.", "", "The directive's sole argument is interpreted as the topic title; the", "next line must be blank. All subsequent lines make up the topic body,", "interpreted as body elements. For example:", "", "```", ".. topic:: Topic Title", "", " Subsequent indented lines comprise", " the body of the topic, and are", " interpreted as body elements.", "```" ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic", "license": "https://docutils.sourceforge.io/docs/" }, "unicode(docutils.parsers.rst.directives.misc.Unicode)": { "is_markdown": true, "description": [ "## Unicode Character Codes", "", "| | |", "|-|-|", "| Directive Type | \"unicode\" |", "| Doctree Element | Text |", "| Directive Arguments | One or more, required (Unicode character codes,", "optional text, and comments). |", "| Directive Options | Possible (see below). |", "| Directive Content | None. |", "", "The \"unicode\" directive converts Unicode character codes (numerical", "values) to characters, and may be used in [substitution definitions](https:/docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions)", "only.", "", "The arguments, separated by spaces, can be:", "- character codes as", "- decimal numbers or", "- hexadecimal numbers, prefixed by `0x`, `x`, `\\x`, `U+`,", "`u`, or `\\u` or as XML-style hexadecimal character entities,", "e.g. `ᨫ`", "- text, which is used as-is.", "", "Text following \" .. \" is a comment and is ignored. The spaces between", "the arguments are ignored and thus do not appear in the output.", "Hexadecimal codes are case-insensitive.", "", "For example, the following text:", "", "```", "Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|", "all rights reserved.", "", ".. |copy| unicode:: 0xA9 .. copyright sign", ".. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122", " .. with trademark sign", ".. |---| unicode:: U+02014 .. em dash", " :trim:", "```", "", "results in:", "", "Copyright \u00a9 2003, BogusMegaCorp\u2122\u2014all rights reserved.", "\u00a9BogusMegaCorp\u2122\u2014", "The following options are recognized:", "", "`ltrim`: flag (empty)", "Whitespace to the left of the substitution reference is removed.", "", "`rtrim`: flag (empty)", "Whitespace to the right of the substitution reference is removed.", "", "`trim`: flag (empty)", "Equivalent to `ltrim` plus `rtrim`; whitespace on both sides", "of the substitution reference is removed." ], "options": { "ltrim": "flag (empty)\nWhitespace to the left of the substitution reference is removed.\n", "rtrim": "flag (empty)\nWhitespace to the right of the substitution reference is removed.\n", "trim": "flag (empty)\nEquivalent to `ltrim` plus `rtrim`; whitespace on both sides\nof the substitution reference is removed.\n" }, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#unicode", "license": "https://docutils.sourceforge.io/docs/" }, "warning(docutils.parsers.rst.directives.admonitions.Warning)": { "is_markdown": true, "description": [ "## Specific Admonitions", "", "| | |", "|-|-|", "| Directive Types | \"attention\", \"caution\", \"danger\", \"error\", \"hint\",", "\"important\", \"note\", \"tip\", \"warning\", \"admonition\" |", "| Doctree Elements | attention, caution, danger, error, hint, important,", "note, tip, warning, [admonition](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#admonition), [title](https:/docutils.sourceforge.io/docs/ref/rst/../doctree.html#title) |", "| Directive Arguments | None. |", "| Directive Options | [class](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#id33), [name](https://docutils.sourceforge.io/docs/ref/rst/directives.txt#name) |", "| Directive Content | Interpreted as body elements. |", "", "Admonitions are specially marked \"topics\" that can appear anywhere an", "ordinary body element can. They contain arbitrary body elements.", "Typically, an admonition is rendered as an offset block in a document,", "sometimes outlined or shaded, with a title matching the admonition", "type. For example:", "", "```", ".. DANGER::", " Beware killer rabbits!", "```", "", "This directive might be rendered something like this:", "", "```", "+------------------------+", "| !DANGER! |", "| |", "| Beware killer rabbits! |", "+------------------------+", "```", "", "The following admonition directives have been implemented:", "- attention", "- caution", "- danger", "- error", "- hint", "- important", "- note", "- tip", "- warning", "", "Any text immediately following the directive indicator (on the same", "line and/or indented on following lines) is interpreted as a directive", "block and is parsed for normal body elements. For example, the", "following \"note\" admonition directive contains one paragraph and a", "bullet list consisting of two list items:", "", "```", ".. note:: This is a note admonition.", " This is the second line of the first paragraph.", "", " - The note contains all indented body elements", " following.", " - It includes this bullet list.", "```" ], "options": {}, "source": "https://docutils.sourceforge.io/docs/ref/rst/directives.html#warning", "license": "https://docutils.sourceforge.io/docs/" } }