API Reference
Contents
API Reference#
Directive Parsing Reference#
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.parse_directives.DirectiveParsingError[source]#
Raise on parsing/validation error.
- myst_parser.parse_directives.parse_directive_text(directive_class: Type[docutils.parsers.rst.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 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(*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.sphinx_renderer.SphinxRenderer(*args, **kwds)[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.
- 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)
.
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: 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: 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.- 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[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('^((?:---?(?!-)|—) *)(.+)')#
- 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: 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
Additional Methods#
- myst_parser.docutils_renderer.make_document(source_path='notset', parser_cls=<class 'docutils.parsers.rst.Parser'>) docutils.nodes.document [source]#
Create a new docutils document, with the parser classes’ default settings.
- myst_parser.docutils_renderer.html_meta_to_nodes(data: Dict[str, Any], document: docutils.nodes.document, line: int, reporter: docutils.utils.Reporter) List[Union[docutils.nodes.pending, docutils.nodes.system_message]] [source]#
Replicate the meta directive, by converting a dictionary to a list of pending meta nodes
See: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#html-metadata
- 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.
Docutils Parser Reference#
Sphinx Parser Reference#
This class builds on the SphinxRenderer
to generate a parser for Sphinx, using the Sphinx parser API:
- class myst_parser.sphinx_parser.MystParser[source]#
Bases:
sphinx.parsers.Parser
Sphinx parser for Markedly Structured Text (MyST).