Python API
Contents
Python API#
Source text parsers#
Docutils#
Sphinx#
- class myst_parser.parsers.sphinx_.MystParser[source]#
Bases:
sphinx.parsers.Parser
Sphinx parser for Markedly Structured Text (MyST).
Markdown-it to docutils#
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.mdit_to_docutils.base.DocutilsRenderer(*args, **kwds)[source]#
Bases:
markdown_it.renderer.RendererProtocol
A markdown-it-py renderer to populate (in-place) a docutils.document AST.
Note, this render is not dependent on Sphinx.
- __init__(parser: markdown_it.main.MarkdownIt) None [source]#
Load the renderer (called by
MarkdownIt
)
- render(tokens: Sequence[markdown_it.token.Token], options, md_env: MutableMapping[str, Any]) docutils.nodes.document [source]#
Run the render on a token stream.
- Parameters
tokens – list on block tokens to render
options – params of parser instance
md_env – the markdown-it environment sandbox associated with the tokens, containing additional metadata like reference info
- nested_render_text(text: str, lineno: int, inline: bool = False, allow_headings: bool = True) None [source]#
Render unparsed text (appending to the current node).
- Parameters
text – the text to render
lineno – the starting line number of the text, within the full source
inline – whether the text is inline or block
allow_headings – whether to allow headings in the text
- current_node_context(node: docutils.nodes.Element, append: bool = False) Iterator [source]#
Context manager for temporarily setting the current node.
- add_line_and_source_path(node, token: markdown_it.tree.SyntaxTreeNode) None [source]#
Copy the line number and document source path to the docutils node.
Sphinx#
- class myst_parser.mdit_to_docutils.sphinx_.SphinxRenderer(*args, **kwds)[source]#
Bases:
myst_parser.mdit_to_docutils.base.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.
- render_internal_link(token: markdown_it.tree.SyntaxTreeNode) None [source]#
Render link token [text](link “title”), where the link has not been identified as an external URL.
- render_math_block_label(token: markdown_it.tree.SyntaxTreeNode) None [source]#
Render math with referencable labels, e.g.
$a=1$ (label)
.
Directive and role processing#
This module processes the content of a directive:
Fenced code blocks are parsed as directives,
if the block starts with {directive_name}
,
followed by arguments on the same line.
Directive options are read from a YAML block,
if the first content line starts with ---
, e.g.
```{directive_name} arguments
---
option1: name
option2: |
Longer text block
---
content...
```
Or the option block will be parsed if the first content line starts with :
,
as a YAML block consisting of every line that starts with a :
, e.g.
```{directive_name} arguments
:option1: name
:option2: other
content...
```
If the first line of a directive’s content is blank, this will be stripped from the content. This is to allow for separation between the option block and content.
- exception myst_parser.parsers.directives.DirectiveParsingError[source]#
Raise on parsing/validation error.
- myst_parser.parsers.directives.parse_directive_text(directive_class: type[Directive], first_line: str, content: str, validate_options: bool = True) tuple[list[str], dict, list[str], int] [source]#
Parse (and validate) the full directive text.
- Parameters
first_line – The text on the same line as the directive name. May be an argument or body text, dependent on the directive
content – All text after the first line. Can include options.
validate_options – Whether to validate the values of options
- Returns
(arguments, options, body_lines, content_offset)
- myst_parser.parsers.directives.parse_directive_options(content: str, directive_class: type[Directive], validate: bool = True)[source]#
Parse (and validate) the directive option section.
- myst_parser.parsers.directives.parse_directive_arguments(directive, arg_text)[source]#
Parse (and validate) the directive argument section.
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: DocutilsRenderer)[source]#
Bases:
object
A mock version of docutils.parsers.rst.states.Inliner.
This is parsed to role functions.
- class myst_parser.mocking.MockState(renderer: DocutilsRenderer, state_machine: 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: StringList, line_offset: int, directive: type[Directive], option_presets: dict) tuple[list, dict, 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.- Parameters
block – The block of lines to parse.
input_offset – The offset of the first line of block, to the starting line of the state (i.e. directive).
node – The parent node to attach the parsed content to.
match_titles – Whether to to allow the parsing of headings (normally this is false, since nested heading would break the document structure)
- 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[nodes.Element], list[nodes.Element]] [source]#
Parse text with only inline rules.
- Returns
(list of nodes, list of messages)
- attribution_pattern = re.compile('^((?:---?(?!-)|—) *)(.+)')#
- class myst_parser.mocking.MockStateMachine(renderer: DocutilsRenderer, lineno: int)[source]#
Bases:
object
A mock version of docutils.parsers.rst.states.RSTStateMachine.
This is parsed to the Directives.run() method.
- class myst_parser.mocking.MockIncludeDirective(renderer: DocutilsRenderer, name: str, klass: 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