docutils.parsers.rst.directives package

This package contains directive implementation modules.

_directive_registry = {'admonition': ('admonitions', 'Admonition'), 'attention': ('admonitions', 'Attention'), 'caution': ('admonitions', 'Caution'), 'class': ('misc', 'Class'), 'code': ('body', 'CodeBlock'), 'compound': ('body', 'Compound'), 'container': ('body', 'Container'), 'contents': ('parts', 'Contents'), 'csv-table': ('tables', 'CSVTable'), 'danger': ('admonitions', 'Danger'), 'date': ('misc', 'Date'), 'default-role': ('misc', 'DefaultRole'), 'epigraph': ('body', 'Epigraph'), 'error': ('admonitions', 'Error'), 'figure': ('images', 'Figure'), 'footer': ('parts', 'Footer'), 'header': ('parts', 'Header'), 'highlights': ('body', 'Highlights'), 'hint': ('admonitions', 'Hint'), 'image': ('images', 'Image'), 'important': ('admonitions', 'Important'), 'include': ('misc', 'Include'), 'line-block': ('body', 'LineBlock'), 'list-table': ('tables', 'ListTable'), 'math': ('body', 'MathBlock'), 'meta': ('misc', 'Meta'), 'note': ('admonitions', 'Note'), 'parsed-literal': ('body', 'ParsedLiteral'), 'pull-quote': ('body', 'PullQuote'), 'raw': ('misc', 'Raw'), 'replace': ('misc', 'Replace'), 'restructuredtext-test-directive': ('misc', 'TestDirective'), 'role': ('misc', 'Role'), 'rubric': ('body', 'Rubric'), 'sectnum': ('parts', 'Sectnum'), 'sidebar': ('body', 'Sidebar'), 'table': ('tables', 'RSTTable'), 'target-notes': ('references', 'TargetNotes'), 'tip': ('admonitions', 'Tip'), 'title': ('misc', 'Title'), 'topic': ('body', 'Topic'), 'unicode': ('misc', 'Unicode'), 'warning': ('admonitions', 'Warning')}

Mapping of directive name to (module name, class name). The directive name is canonical & must be lowercase. Language-dependent names are defined in the language subpackage.

_directives = {'acks': <class 'sphinx.directives.other.Acks'>, 'autoattribute': <class 'sphinx.ext.autodoc.directive.AutodocDirective'>, 'autoclass': <class 'sphinx.ext.autodoc.directive.AutodocDirective'>, 'autodata': <class 'sphinx.ext.autodoc.directive.AutodocDirective'>, 'autodecorator': <class 'sphinx.ext.autodoc.directive.AutodocDirective'>, 'autoexception': <class 'sphinx.ext.autodoc.directive.AutodocDirective'>, 'autofunction': <class 'sphinx.ext.autodoc.directive.AutodocDirective'>, 'automethod': <class 'sphinx.ext.autodoc.directive.AutodocDirective'>, 'automodule': <class 'sphinx.ext.autodoc.directive.AutodocDirective'>, 'autoproperty': <class 'sphinx.ext.autodoc.directive.AutodocDirective'>, 'centered': <class 'sphinx.directives.other.Centered'>, 'code': <class 'sphinx.directives.patches.Code'>, 'code-block': <class 'sphinx.directives.code.CodeBlock'>, 'codeauthor': <class 'sphinx.directives.other.Author'>, 'cssclass': <class 'docutils.parsers.rst.directives.misc.Class'>, 'csv-table': <class 'sphinx.directives.patches.CSVTable'>, 'default-domain': <class 'sphinx.directives.DefaultDomain'>, 'default-role': <class 'sphinx.directives.DefaultRole'>, 'deprecated': <class 'sphinx.domains.changeset.VersionChange'>, 'describe': <class 'sphinx.directives.ObjectDescription'>, 'figure': <class 'sphinx.directives.patches.Figure'>, 'highlight': <class 'sphinx.directives.code.Highlight'>, 'hlist': <class 'sphinx.directives.other.HList'>, 'include': <class 'sphinx.directives.other.Include'>, 'index': <class 'sphinx.domains.index.IndexDirective'>, 'literalinclude': <class 'sphinx.directives.code.LiteralInclude'>, 'math': <class 'sphinx.directives.patches.MathDirective'>, 'meta': <class 'docutils.parsers.rst.directives.misc.Meta'>, 'moduleauthor': <class 'sphinx.directives.other.Author'>, 'object': <class 'sphinx.directives.ObjectDescription'>, 'only': <class 'sphinx.directives.other.Only'>, 'readthedocs-embed': <class 'readthedocs_ext.embed.EmbedDirective'>, 'rst-class': <class 'docutils.parsers.rst.directives.misc.Class'>, 'sectionauthor': <class 'sphinx.directives.other.Author'>, 'seealso': <class 'sphinx.directives.other.SeeAlso'>, 'sourcecode': <class 'sphinx.directives.code.CodeBlock'>, 'tabularcolumns': <class 'sphinx.directives.other.TabularColumns'>, 'toctree': <class 'sphinx.directives.other.TocTree'>, 'versionadded': <class 'sphinx.domains.changeset.VersionChange'>, 'versionchanged': <class 'sphinx.domains.changeset.VersionChange'>}

Cache of imported directives.

register_directive(name, directive)

Register a nonstandard application-defined directive function. Language lookups are not needed for such functions.

flag(argument)

Check for a valid flag option (no argument) and return None. (Directive option conversion function.)

Raise ValueError if an argument is found.

unchanged_required(argument)

Return the argument text, unchanged. (Directive option conversion function.)

Raise ValueError if no argument is found.

unchanged(argument)

Return the argument text, unchanged. (Directive option conversion function.)

No argument implies empty string (“”).

path(argument)

Return the path argument unwrapped (with newlines removed). (Directive option conversion function.)

Raise ValueError if no argument is found.

uri(argument)

Return the URI argument with unescaped whitespace removed. (Directive option conversion function.)

Raise ValueError if no argument is found.

nonnegative_int(argument)

Check for a nonnegative integer argument; raise ValueError if not. (Directive option conversion function.)

percentage(argument)

Check for an integer percentage value with optional percent sign. (Directive option conversion function.)

get_measure(argument, units)

Check for a positive argument of one of the units and return a normalized string of the form “<value><unit>” (without space in between). (Directive option conversion function.)

To be called from directive option conversion functions.

length_or_unitless(argument)

length_or_percentage_or_unitless(argument, default='')

Return normalized string of a length or percentage unit. (Directive option conversion function.)

Add <default> if there is no unit. Raise ValueError if the argument is not a positive measure of one of the valid CSS units (or without unit).

>>> length_or_percentage_or_unitless('3 pt')
'3pt'
>>> length_or_percentage_or_unitless('3%', 'em')
'3%'
>>> length_or_percentage_or_unitless('3')
'3'
>>> length_or_percentage_or_unitless('3', 'px')
'3px'

class_option(argument)

Convert the argument into a list of ID-compatible strings and return it. (Directive option conversion function.)

Raise ValueError if no argument is found.

unicode_code(code)

Convert a Unicode character code to a Unicode character. (Directive option conversion function.)

Codes may be decimal numbers, hexadecimal numbers (prefixed by 0x, x, \x, U+, u, or \u; e.g. U+262E), or XML-style numeric character entities (e.g. ☮). Other text remains as-is.

Raise ValueError for illegal Unicode code values.

single_char_or_unicode(argument)

A single character is returned as-is. Unicode character codes are converted as in unicode_code. (Directive option conversion function.)

single_char_or_whitespace_or_unicode(argument)

As with single_char_or_unicode, but “tab” and “space” are also supported. (Directive option conversion function.)

positive_int(argument)

Converts the argument into an integer. Raises ValueError for negative, zero, or non-integer values. (Directive option conversion function.)

positive_int_list(argument)

Converts a space- or comma-separated list of values into a Python list of integers. (Directive option conversion function.)

Raises ValueError for non-positive-integer values.

encoding(argument)

Verifies the encoding argument by lookup. (Directive option conversion function.)

Raises ValueError for unknown encodings.

choice(argument, values)

Directive option utility function, supplied to enable options whose argument must be a member of a finite set of possible values (must be lower case). A custom conversion function must be written to use it. For example:

from docutils.parsers.rst import directives

def yesno(argument):
    return directives.choice(argument, ('yes', 'no'))

Raise ValueError if no argument is found or if the argument’s value is not valid (not an entry in the supplied list).

format_values(values)

value_or(values, other)

Directive option conversion function.

The argument can be any of values or argument_type.

parser_name(argument)

Return a docutils parser whose name matches the argument. (Directive option conversion function.)

Return None, if the argument evaluates to False. Raise ValueError if importing the parser module fails.

Submodules

• docutils.parsers.rst.directives.admonitions module
• docutils.parsers.rst.directives.body module
• docutils.parsers.rst.directives.html module
• docutils.parsers.rst.directives.images module
• docutils.parsers.rst.directives.misc module
• docutils.parsers.rst.directives.parts module
• docutils.parsers.rst.directives.references module
• docutils.parsers.rst.directives.tables module