API Reference
*************

This document is for developers of recommonmark, it contans the API
functions


Parser Component
================

class recommonmark.parser.CommonMarkParser

   Bases: "Parser"

   Docutils parser for CommonMark

   default_depart(mdnode)

      Default node depart handler

      If there is a matching "visit_<type>" method for a container
      node, then we should make sure to back up to it's parent element
      when the node is exited.

   depart_heading(_)

      Finish establishing section

      Wrap up title node, but stick in the section node. Add the
      section names based on all the text nodes added to the title.

   parse(inputstring, document)

      Override to parse *inputstring* into document tree *document*.

   supported = ('md', 'markdown')

      Name and aliases for this component.  Override in subclasses.


Dummy State Machine
===================

class recommonmark.states.DummyStateMachine

   Bases: "StateMachineWS"

   A dummy state machine that mimicks the property of statemachine.

   This state machine cannot be used for parsing, it is only used to
   generate directive and roles. Usage: - Call *reset* to reset the
   state - Then call *run_directive* or *run_role* to generate the
   node.

   get_source_and_line(lineno=None)

      Return (source, line) tuple for current or given line number.

      Looks up the source and line number in the *self.input_lines*
      StringList instance to count for included source files.

      If the optional argument *lineno* is given, convert it from an
      absolute line number to the corresponding (source, line) pair.

   reset(document, parent, level)

      Reset the state of state machine.

      After reset, self and self.state can be used to passed to
      docutils.parsers.rst.Directive.run

      Parameters:
         * **document** (*docutils document*) -- Current document of
           the node.

         * **parent** (*parent node*) -- Parent node that will be used
           to interpret role and directives.

         * **level** (*int*) -- Current section level.

   run_directive(name, arguments=None, options=None, content=None)

      Generate directive node given arguments.

      Parameters:
         * **name** (*str*) -- name of directive.

         * **arguments** (*list*) -- list of positional arguments.

         * **options** (*dict*) -- key value arguments.

         * **content** (*content*) -- content of the directive

      Returns:
         **node** -- Node generated by the arguments.

      Return type:
         docutil Node

   run_role(name, options=None, content=None)

      Generate a role node.

      options : dict
         key value arguments.

      content : content
         content of the directive

      Returns:
         **node** -- Node generated by the arguments.

      Return type:
         docutil Node


AutoStructify Transformer
=========================

class recommonmark.transform.AutoStructify(*args, **kwargs)

   Bases: "Transform"

   Automatically try to transform blocks to sphinx directives.

   This class is designed to handle AST generated by CommonMarkParser.

   apply()

      Apply the transformation by configuration.

   auto_code_block(node)

      Try to automatically generate nodes for codeblock syntax.

      Parameters:
         **node** (*nodes.literal_block*) -- Original codeblock node

      Returns:
         **tocnode** -- The converted toc tree node, None if
         conversion is not possible.

      Return type:
         docutils node

   auto_inline_code(node)

      Try to automatically generate nodes for inline literals.

      Parameters:
         **node** (*nodes.literal*) -- Original codeblock node

      Returns:
         **tocnode** -- The converted toc tree node, None if
         conversion is not possible.

      Return type:
         docutils node

   auto_toc_tree(node)

      Try to convert a list block to toctree in rst.

      This function detects if the matches the condition and return a
      converted toc tree node. The matching condition: The list only
      contains one level, and only contains references

      Parameters:
         **node** (*nodes.Sequential*) -- A list node in the doctree

      Returns:
         **tocnode** -- The converted toc tree node, None if
         conversion is not possible.

      Return type:
         docutils node

   default_priority = 1

      Numerical priority of this transform, 0 through 999 (override).

   find_replace(node)

      Try to find replace node for current node.

      Parameters:
         **node** (*docutil node*) -- Node to find replacement for.

      Returns:
         **nodes** -- The replacement nodes of current node. Returns
         None if no replacement can be found.

      Return type:
         node or list of node

   parse_ref(ref)

      Analyze the ref block, and return the information needed.

      Parameters:
         **ref** (*nodes.reference*) --

      Returns:
         **result** -- The returned result is tuple of (title, uri,
         docpath). title is the display title of the ref. uri is the
         html uri of to the ref after resolve. docpath is the absolute
         document path to the document, if the target corresponds to
         an internal document, this can bex None

      Return type:
         tuple of (str, str, str)

   traverse(node)

      Traverse the document tree rooted at node.

      node : docutil node
         current root node to traverse
