API Reference

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

Parser Component

class recommonmark.parser.CommonMarkParser

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

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.

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.

optionsdict

key value arguments.

contentcontent

content of the directive

Returns

node – Node generated by the arguments.

Return type

docutil Node

AutoStructify Transformer

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

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_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.

nodedocutil node

current root node to traverse