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[源代码]¶: 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)[源代码]¶

Parse (and validate) the full directive text.

参数

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

myst_parser.parse_directives.parse_directive_options(content: str, directive_class: Type[docutils.parsers.rst.Directive], validate: bool = True)[源代码]¶: Parse (and validate) the directive option section.

myst_parser.parse_directives.parse_directive_arguments(directive, arg_text)[源代码]¶: Parse (and validate) the directive argument section.

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)[源代码]¶

基类：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.

__output__: ClassVar[str] = 'docutils'¶

__init__(parser: markdown_it.main.MarkdownIt) → None[源代码]¶: Load the renderer (called by MarkdownIt)

render(tokens: Sequence[markdown_it.token.Token], options, md_env: MutableMapping[str, Any]) → docutils.nodes.document[源代码]¶

Run the render on a token stream.

参数

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) → None[源代码]¶: Render unparsed text.

current_node_context(node: docutils.nodes.Element, append: bool = False) → Iterator[源代码]¶: Context manager for temporarily setting the current node.

add_line_and_source_path(node, token: markdown_it.tree.SyntaxTreeNode) → None[源代码]¶: Copy the line number and document source path to the docutils node.

Sphinx¶

class myst_parser.sphinx_renderer.SphinxRenderer(parser: markdown_it.main.MarkdownIt)[源代码]¶

基类：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__: ClassVar[str] = 'docutils'¶

handle_cross_reference(token: markdown_it.tree.SyntaxTreeNode, destination: str) → None[源代码]¶: Create nodes for references that are not immediately resolvable.

render_math_block_label(token: markdown_it.tree.SyntaxTreeNode) → None[源代码]¶: 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, lineno: int)[源代码]¶

基类：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) → docutils.nodes.problematic[源代码]¶

class myst_parser.mocking.MockState(renderer: DocutilsRenderer, state_machine: MockStateMachine, lineno: int)[源代码]¶

基类：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][源代码]¶

Parse the full directive text

返回: (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[源代码]¶: Perform a nested parse of the input block, with node as the parent.

parse_target(block, block_text, lineno: int)[源代码]¶: 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]][源代码]¶

Parse text with only inline rules.

返回: (list of nodes, list of messages)

attribution_pattern = re.compile('^((?:---?(?!-)|—) *)(.+)')¶

block_quote(lines: List[str], line_offset: int) → List[docutils.nodes.Element][源代码]¶

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: int = 0, widths=None)[源代码]¶

build_table_row(rowdata, tableline)[源代码]¶

class myst_parser.mocking.MockStateMachine(renderer: DocutilsRenderer, lineno: int)[源代码]¶

基类：object

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

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

get_source(lineno: Optional[int] = None)[源代码]¶: Return document source path.

get_source_and_line(lineno: Optional[int] = None)[源代码]¶: Return (source path, line) tuple for current or given line number.

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)[源代码]¶

基类：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() → List[docutils.nodes.Element][源代码]¶

add_name(node: docutils.nodes.Element)[源代码]¶

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', parser_cls=<class 'docutils.parsers.rst.Parser'>) → docutils.nodes.document[源代码]¶: 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]][源代码]¶

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)[源代码]¶: 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)[源代码]¶

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

参数

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¶

class myst_parser.docutils_.Parser(rfc2822=False, inliner=None)[源代码]¶

基类：docutils.parsers.rst.Parser

Docutils parser for Markedly Structured Text (MyST).

parse(inputstring: str, document: docutils.nodes.document) → None[源代码]¶

Parse source text.

参数

inputstring – The source string to parse
document – The root docutils node to add AST elements to

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[源代码]¶

基类：sphinx.parsers.Parser

Sphinx parser for Markedly Structured Text (MyST).

supported: Tuple[str, ...] = ('md', 'markdown', 'myst')¶: Aliases this parser supports.

parse(inputstring: str, document: docutils.nodes.document) → None[源代码]¶

Parse source text.

参数

inputstring – The source string to parse
document – The root docutils node to add AST elements to