docutils.parsers.rst.directives

Package docutils :: Package parsers :: Package rst :: Package directives

[show private | hide private]

Package docutils.parsers.rst.directives

This package contains directive implementation modules.

The interface for directive functions is as follows:

def directive_fn(name, arguments, options, content, lineno,
                 content_offset, block_text, state, state_machine):
    code...

# Set function attributes:
directive_fn.arguments = ...
directive_fn.options = ...
direcitve_fn.content = ...

Parameters:

name is the directive type or name.
arguments is a list of positional arguments.
options is a dictionary mapping option names to values.
content is a list of strings, the directive content.
lineno is the line number of the first line of the directive.
content_offset is the line offset of the first line of the content from the beginning of the current input. Used when initiating a nested parse.
block_text is a string containing the entire directive. Include it as the content of a literal block in a system message if there is a problem.
state is the state which called the directive function.
state_machine is the state machine which controls the state which called the directive function.

Function attributes, interpreted by the directive parser (which calls the directive function):

arguments: A 3-tuple specifying the expected positional arguments, or None if the directive has no arguments. The 3 items in the tuple are (required, optional, whitespace OK in last argument):
1. The number of required arguments.
2. The number of optional arguments.
3. A boolean, indicating if the final argument may contain whitespace.
Arguments are normally single whitespace-separated words. The final argument may contain whitespace if the third item in the argument spec tuple is 1/True. If the form of the arguments is more complex, specify only one argument (either required or optional) and indicate that final whitespace is OK; the client code must do any context-sensitive parsing.
options: A dictionary, mapping known option names to conversion functions such as int or float. None or an empty dict implies no options to parse.
content: A boolean; true if content is allowed. Client code must handle the case where content is required but not supplied (an empty content list will be supplied).

Directive functions return a list of nodes which will be inserted into the document tree at the point where the directive was encountered (can be an empty list).

See Creating reStructuredText Directives for more information.

Submodules
`admonitions`: Admonition directives. `body`: Directives for additional body elements. `html`: Directives for typically HTML-specific constructs. `images`: Directives for figures and simple images. `misc`: Miscellaneous directives. `parts`: Directives for document parts. `references`: Directives for references and targets.

Function Summary
	`choice(argument, values)`
	`class_option(argument)`
	`directive(directive_name, language_module, document)` Locate and return a directive function from its language-dependent name.
	`flag(argument)` Check for a valid flag option (no argument) and return `None`.
	`format_values(values)`
	`nonnegative_int(argument)` Check for a nonnegative integer argument; raise `ValueError` if not.
	`path(argument)` Return the path argument unwrapped (with newlines removed).
	`register_directive(name, directive)` Register a nonstandard application-defined directive function.
	`unchanged(argument)` Return the argument, unchanged.

Function Details

directive(directive_name, language_module, document)

Locate and return a directive function from its language-dependent name. If not found in the current language, check English. Return None if the named directive cannot be found.

flag(argument)

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

Raise ValueError if an argument is found.

nonnegative_int(argument)

Check for a nonnegative integer argument; raise ValueError if not.

path(argument)

Return the path argument unwrapped (with newlines removed).

Raise ValueError if no argument is found or if the path contains internal whitespace.

register_directive(name, directive)

unchanged(argument)

Return the argument, unchanged.

Raise ValueError if no argument is found.

Generated by Epydoc 2.0 on Tue Jul 22 05:31:05 2003

http://epydoc.sf.net