Docutils markup API

This section describes the API for adding ReST markup elements (roles and directives).

Roles

Directives

Directives are handled by classes derived from docutils.parsers.rst.Directive. They have to be registered by an extension using Sphinx.add_directive() or Sphinx.add_directive_to_domain().

class docutils.parsers.rst.Directive

The markup syntax of the new directive is determined by the follow five class attributes:

required_arguments = 0

Number of required directive arguments.

optional_arguments = 0

Number of optional arguments after the required arguments.

final_argument_whitespace = False

May the final argument contain whitespace?

option_spec = None

Mapping of option names to validator functions.

Option validator functions take a single parameter, the option argument (or None if not given), and should validate it or convert it to the proper form. They raise ValueError or TypeError to indicate failure.

There are several predefined and possibly useful validators in the docutils.parsers.rst.directives module.

has_content = False

May the directive have content?

New directives must implement the run() method:

run()

This method must process the directive arguments, options and content, and return a list of Docutils/Sphinx nodes that will be inserted into the document tree at the point where the directive was encountered.

Instance attributes that are always set on the directive are:

name

The directive name (useful when registering the same directive class under multiple names).

arguments

The arguments given to the directive, as a list.

options

The options given to the directive, as a dictionary mapping option names to validated/converted values.

content

The directive content, if given, as a ViewList.

lineno

The absolute line number on which the directive appeared. This is not always a useful value; use srcline instead.

content_offset

Internal offset of the directive content. Used when calling nested_parse (see below).

block_text

The string containing the entire directive.

state

state_machine

The state and state machine which controls the parsing. Used for nested_parse.

ViewLists

Docutils represents document source lines in a class docutils.statemachine.ViewList. This is a list with extended functionality – for one, slicing creates views of the original list, and also the list contains information about the source line numbers.

The Directive.content attribute is a ViewList. If you generate content to be parsed as ReST, you have to create a ViewList yourself. Important for content generation are the following points:

• The constructor takes a list of strings (lines) and a source (document) name.

• The .append() method takes a line and a source name as well.

Parsing directive content as ReST

Many directives will contain more markup that must be parsed. To do this, use one of the following APIs from the Directive.run() method:

• self.state.nested_parse

• sphinx.util.nodes.nested_parse_with_titles() – this allows titles in the parsed content.

Both APIs parse the content into a given node. They are used like this:

node = docutils.nodes.paragraph()
# either
nested_parse_with_titles(self.state, self.result, node)
# or
self.state.nested_parse(self.result, 0, node)

备注

sphinx.util.docutils.switch_source_input() allows to change a target file during nested_parse. It is useful to mixed contents. For example, sphinx. ext.autodoc uses it to parse docstrings:

from sphinx.util.docutils import switch_source_input

# Switch source_input between parsing content.
# Inside this context, all parsing errors and warnings are reported as
# happened in new source_input (in this case, ``self.result``).
with switch_source_input(self.state, self.result):
    node = docutils.nodes.paragraph()
    self.state.nested_parse(self.result, 0, node)

1.7 版后已移除: Until Sphinx-1.6, sphinx.ext.autodoc.AutodocReporter is used for this purpose. For now, it is replaced by switch_source_input().

If you don’t need the wrapping node, you can use any concrete node type and return node.children from the Directive.

参见

Creating directives HOWTO of the Docutils documentation