MyST Renderers

These renderers take the markdown-it parsed token stream and convert it to the docutils AST. The sphinx renderer is a subclass of the docutils one, with some additional methods only available via sphinx .e.g. multi-document cross-referencing.

Docutils

class myst_parser.docutils_renderer.DocutilsRenderer(parser: markdown_it.main.MarkdownIt)[source]

Bases: object

A markdown-it-py renderer to populate (in-place) a docutils.document AST.

Note, this render is not dependent on Sphinx.

__output__ = 'docutils'
__init__(parser: markdown_it.main.MarkdownIt)[source]

Load the renderer (called by MarkdownIt)

render(tokens: List[markdown_it.token.Token], options, env: markdown_it.utils.AttrDict)[source]

Run the render on a token stream.

Parameters
  • tokens – list on block tokens to render

  • options – params of parser instance

  • env – the environment sandbox associated with the tokens, containing additional metadata like reference info

nested_render_text(text: str, lineno: int)[source]

Render unparsed text.

current_node_context(node, append: bool = False)[source]

Context manager for temporarily setting the current node.

add_line_and_source_path(node, token)[source]

Copy the line number and document source path to the docutils node.

Sphinx

class myst_parser.sphinx_renderer.SphinxRenderer(parser: markdown_it.main.MarkdownIt)[source]

Bases: myst_parser.docutils_renderer.DocutilsRenderer

A markdown-it-py renderer to populate (in-place) a docutils.document AST.

This is sub-class of DocutilsRenderer that handles sphinx specific aspects, such as cross-referencing.

__output__ = 'docutils'
handle_cross_reference(token, destination)[source]

Create nodes for references that are not immediately resolvable.

render_math_block_eqno(token)[source]

Render math with referencable labels, e.g. $a=1$ (label).

Mocking

These classes are parsed to sphinx roles and directives, to mimic the original docutls rST specific parser elements, but instead run nested parsing with the markdown parser.

class myst_parser.mocking.MockInliner(renderer, lineno: int)[source]

Bases: object

A mock version of docutils.parsers.rst.states.Inliner.

This is parsed to role functions.

problematic(text: str, rawsource: str, message: docutils.nodes.system_message)[source]
class myst_parser.mocking.MockState(renderer, state_machine: myst_parser.mocking.MockStateMachine, lineno: int)[source]

Bases: object

A mock version of docutils.parsers.rst.states.RSTState.

This is parsed to the Directives.run() method, so that they may run nested parses on their content that will be parsed as markdown, rather than RST.

parse_directive_block(content: docutils.statemachine.StringList, line_offset: int, directive: Type[docutils.parsers.rst.Directive], option_presets: dict) → Tuple[list, dict, docutils.statemachine.StringList, int][source]

Parse the full directive text

Returns

(arguments, options, content, content_offset)

nested_parse(block: docutils.statemachine.StringList, input_offset: int, node: docutils.nodes.Element, match_titles: bool = False, state_machine_class=None, state_machine_kwargs=None)None[source]

Perform a nested parse of the input block, with node as the parent.

parse_target(block, block_text, lineno: int)[source]

Taken from https://github.com/docutils-mirror/docutils/blob/e88c5fb08d5cdfa8b4ac1020dd6f7177778d5990/docutils/parsers/rst/states.py#L1927 # noqa: E501

inline_text(text: str, lineno: int) → Tuple[List[docutils.nodes.Element], List[docutils.nodes.Element]][source]

Parse text with only inline rules.

Returns

(list of nodes, list of messages)

attribution_pattern = re.compile('^((?:---?(?!-)|—) *)(.+)')
block_quote(lines: List[str], line_offset: int) → List[docutils.nodes.Element][source]

Parse a block quote, which is a block of text, followed by an (optional) attribution.

No matter where you go, there you are.

-- Buckaroo Banzai
build_table(tabledata, tableline, stub_columns=0, widths=None)[source]
build_table_row(rowdata, tableline)[source]
class myst_parser.mocking.MockStateMachine(renderer, lineno: int)[source]

Bases: object

A mock version of docutils.parsers.rst.states.RSTStateMachine.

This is parsed to the Directives.run() method.

get_source(lineno: Optional[int] = None)[source]

Return document source path.

get_source_and_line(lineno: Optional[int] = None)[source]

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

class myst_parser.mocking.MockIncludeDirective(renderer, name: str, klass: docutils.parsers.rst.directives.misc.Include, arguments: list, options: dict, body: List[str], lineno: int)[source]

Bases: object

This directive uses a lot of statemachine logic that is not yet mocked. Therefore, we treat it as a special case (at least for now).

See: https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment

run()[source]
add_name(node)[source]

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

Additional Methods

myst_parser.docutils_renderer.make_document(source_path='notset') → docutils.nodes.document[source]

Create a new docutils document.

myst_parser.docutils_renderer.dict_to_field_list(data: dict) → docutils.nodes.field_list[source]

Render each key/val pair as a docutils field node.

If the field list is at the start of the document, then it will be converted to a docinfo node during the docutils.docutils.transforms.frontmatter.DocInfo transform (priority 340), and bibliographic keys will be converted to specific nodes:

{'author': docutils.nodes.author,
'authors': docutils.nodes.authors,
'organization': docutils.nodes.organization,
'address': docutils.nodes.address,
'contact': docutils.nodes.contact,
'version': docutils.nodes.version,
'revision': docutils.nodes.revision,
'status': docutils.nodes.status,
'date': docutils.nodes.date,
'copyright': docutils.nodes.copyright,
'dedication': docutils.nodes.topic,
'abstract': docutils.nodes.topic}

If using sphinx, this docinfo node will later be extracted from the AST, by the DoctreeReadEvent transform (priority 880), calling MetadataCollector.process_doc. In this case keys and values will be converted to strings and stored in app.env.metadata[app.env.docname]

See https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html for docinfo fields used by sphinx.

myst_parser.sphinx_renderer.minimal_sphinx_app(configuration=None, sourcedir=None, with_builder=False, raise_on_warning=False)[source]

Create a minimal Sphinx environment; loading sphinx roles, directives, etc.

myst_parser.sphinx_renderer.mock_sphinx_env(conf=None, srcdir=None, document=None, with_builder=False, raise_on_warning=False)[source]

Set up an environment, to parse sphinx roles/directives, outside of a sphinx-build.

Parameters
  • conf – a dictionary representation of the sphinx conf.py

  • srcdir – a path to a source directory (for example, can be used for include statements)

This primarily copies the code in sphinx.util.docutils.docutils_namespace and sphinx.util.docutils.sphinx_domains.