API Reference

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

Parser Component

class recommonmark.parser.CommonMarkParser

Bases: docutils.parsers.Parser

Parser of recommonmark.

Dummy State Machine

class recommonmark.states.DummyStateMachine

Bases: docutils.statemachine.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.

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(document, startnode=None)

Bases: docutils.transforms.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_doc_ref(node)

Try to convert a reference to docref in rst.

Parameters:node (nodes.reference) – A reference node in doctree. 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

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