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)

Note:

  "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)

  Deprecated since version 1.7: Until Sphinx 1.6,
  "sphinx.ext.autodoc.AutodocReporter" was used for this purpose.  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.

See also: Creating directives HOWTO of the Docutils documentation
