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.

settings_spec = ('Generic Parser Options', None, (('Disable directives that insert the contents of an external file; replaced with a "warning" system message.', ['--no-file-insertion'], {'action': 'store_false', 'default': 1, 'dest': 'file_insertion_enabled', 'validator': <function validate_boolean>}), ('Enable directives that insert the contents of an external file. (default)', ['--file-insertion-enabled'], {'action': 'store_true'}), ('Disable the "raw" directive; replaced with a "warning" system message.', ['--no-raw'], {'action': 'store_false', 'default': 1, 'dest': 'raw_enabled', 'validator': <function validate_boolean>}), ('Enable the "raw" directive. (default)', ['--raw-enabled'], {'action': 'store_true'}), ('Maximal number of characters in an input line. Default 10 000.', ['--line-length-limit'], {'default': 10000, 'metavar': '<length>', 'type': 'int', 'validator': <function validate_nonnegative_int>})), 'reStructuredText Parser Options', None, (('Recognize and link to standalone PEP references (like "PEP 258").', ['--pep-references'], {'action': 'store_true', 'validator': <function validate_boolean>}), ('Base URL for PEP references (default "https://peps.python.org/").', ['--pep-base-url'], {'default': 'https://peps.python.org/', 'metavar': '<URL>', 'validator': <function validate_url_trailing_slash>}), ('Template for PEP file part of URL. (default "pep-%04d")', ['--pep-file-url-template'], {'default': 'pep-%04d', 'metavar': '<URL>'}), ('Recognize and link to standalone RFC references (like "RFC 822").', ['--rfc-references'], {'action': 'store_true', 'validator': <function validate_boolean>}), ('Base URL for RFC references (default "https://tools.ietf.org/html/").', ['--rfc-base-url'], {'default': 'https://tools.ietf.org/html/', 'metavar': '<URL>', 'validator': <function validate_url_trailing_slash>}), ('Set number of spaces for tab expansion (default 8).', ['--tab-width'], {'default': 8, 'metavar': '<width>', 'type': 'int', 'validator': <function validate_nonnegative_int>}), ('Remove spaces before footnote references.', ['--trim-footnote-reference-space'], {'action': 'store_true', 'validator': <function validate_boolean>}), ('Leave spaces before footnote references.', ['--leave-footnote-reference-space'], {'action': 'store_false', 'dest': 'trim_footnote_reference_space'}), ('Token name set for parsing code with Pygments: one of "long", "short", or "none" (no parsing). Default is "long".', ['--syntax-highlight'], {'choices': ['long', 'short', 'none'], 'default': 'long', 'metavar': '<format>'}), ('Change straight quotation marks to typographic form: one of "yes", "no", "alt[ernative]" (default "no").', ['--smart-quotes'], {'default': False, 'metavar': '<yes/no/alt>', 'validator': <function validate_ternary>}), ('Characters to use as "smart quotes" for <language>. ', ['--smartquotes-locales'], {'action': 'append', 'metavar': '<language:quotes[,language:quotes,...]>', 'validator': <function validate_smartquotes_locales>}), ('Inline markup recognized at word boundaries only (adjacent to punctuation or whitespace). Force character-level inline markup recognition with "\\ " (backslash + space). Default.', ['--word-level-inline-markup'], {'action': 'store_false', 'dest': 'character_level_inline_markup'}), ('Inline markup recognized anywhere, regardless of surrounding characters. Backslash-escapes must be used to avoid unwanted markup recognition. Useful for East Asian languages. Experimental.', ['--character-level-inline-markup'], {'action': 'store_true', 'default': False, 'dest': 'character_level_inline_markup'})))

Runtime settings specification. Override in subclasses.

Defines runtime settings and associated command-line options, as used by docutils.frontend.OptionParser. This is a tuple of:

  • Option group title (string or None which implies no group, just a list of single options).

  • Description (string or None).

  • A sequence of option tuples. Each consists of:

    • Help text (string)

    • List of option strings (e.g. ['-Q', '--quux']).

    • Dictionary of keyword arguments sent to the OptionParser/OptionGroup add_option method.

      Runtime setting names are derived implicitly from long option names (’–a-setting’ becomes settings.a_setting) or explicitly from the ‘dest’ keyword argument.

      Most settings will also have a ‘validator’ keyword & function. The validator function validates setting values (from configuration files and command-line option arguments) and converts them to appropriate types. For example, the docutils.frontend.validate_boolean function, required by all boolean settings, converts true values (‘1’, ‘on’, ‘yes’, and ‘true’) to 1 and false values (‘0’, ‘off’, ‘no’, ‘false’, and ‘’) to 0. Validators need only be set once per setting. See the docutils.frontend.validate_* functions.

      See the optparse docs for more details.

  • More triples of group title, description, options, as many times as needed. Thus, settings_spec tuples can be simply concatenated.

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.

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

nodedocutil node

current root node to traverse