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
-
current_node_context
(node: docutils.nodes.Element, append: bool = False)[source]¶ Context manager for temporarily setting the current node.
-
add_line_and_source_path
(node, token: Union[markdown_it.token.Token, markdown_it.token.NestedTokens])[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: markdown_it.token.Token, destination: str)[source]¶ Create nodes for references that are not immediately resolvable.
-
render_math_block_eqno
(token: markdown_it.token.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: DocutilsRenderer, lineno: int)[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.
-
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') → docutils.nodes.document[source]¶ Create a new docutils document.
-
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.