Inheritance diagram for myst_parser.mdit_to_docutils.base.DocutilsRenderer:

Collaboration diagram for myst_parser.mdit_to_docutils.base.DocutilsRenderer:

Public Member Functions
None	__init__ (self, MarkdownIt parser)

	__getattr__ (self, str name)

None	setup_render (self, dict[str, Any] options, MutableMapping[str, Any] env)

BuildEnvironment\|None	sphinx_env (self)

nodes.system_message\|None	create_warning (self, str message, MystWarnings\|str subtype, *str\|None wtype=None, int\|None line=None, nodes.Element\|None append_to=None)

nodes.document	render (self, Sequence[Token] tokens, options, MutableMapping[str, Any] md_env)

None	nested_render_text (self, str text, int lineno, bool inline=False, None\|nodes.Element temp_root_node=None, int heading_offset=0)

Iterator[None]	current_node_context (self, nodes.Element node, bool append=False)

None	render_children (self, SyntaxTreeNode token)

None	add_line_and_source_path (self, node, SyntaxTreeNode token)

None	add_line_and_source_path_r (self, list[nodes.Element] nodes_, SyntaxTreeNode token)

None	copy_attributes (self, SyntaxTreeNode token, nodes.Element node, Sequence[str] keys=("class",), *dict[str, Callable[[str], Any]]\|None converters=None, dict[str, str]\|None aliases=None)

None	update_section_level_state (self, nodes.section section, int level)

str	renderInlineAsText (self, list[SyntaxTreeNode] tokens)

None	render_paragraph (self, SyntaxTreeNode token)

None	render_inline (self, SyntaxTreeNode token)

None	render_text (self, SyntaxTreeNode token)

None	render_bullet_list (self, SyntaxTreeNode token)

None	render_ordered_list (self, SyntaxTreeNode token)

None	render_list_item (self, SyntaxTreeNode token)

None	render_em (self, SyntaxTreeNode token)

None	render_softbreak (self, SyntaxTreeNode token)

None	render_hardbreak (self, SyntaxTreeNode token)

None	render_strong (self, SyntaxTreeNode token)

None	render_blockquote (self, SyntaxTreeNode token)

None	render_hr (self, SyntaxTreeNode token)

None	render_code_inline (self, SyntaxTreeNode token)

nodes.Element	create_highlighted_code_block (self, str text, str\|None lexer_name, bool number_lines=False, int lineno_start=1, str\|None source=None, int\|None line=None, type[nodes.Element] node_cls=nodes.literal_block, list[int]\|str\|None emphasize_lines=None)

None	render_code_block (self, SyntaxTreeNode token)

None	render_fence (self, SyntaxTreeNode token)

bool	blocks_mathjax_processing (self)

None	generate_heading_target (self, SyntaxTreeNode token, int level, nodes.Element node, nodes.Element title_node)

None	render_heading (self, SyntaxTreeNode token)

None	render_link (self, SyntaxTreeNode token)

None	render_link_url (self, SyntaxTreeNode token, None\|UrlSchemeType conversion=None)

None	render_link_path (self, SyntaxTreeNode token)

None	render_link_project (self, SyntaxTreeNode token)

None	render_link_anchor (self, SyntaxTreeNode token, str target)

None	render_link_unknown (self, SyntaxTreeNode token)

None	render_link_inventory (self, SyntaxTreeNode token)

list[inventory.InvMatch]	get_inventory_matches (self, *str\|None invs, str\|None domains, str\|None otypes, str\|None target)

None	render_html_inline (self, SyntaxTreeNode token)

None	render_html_block (self, SyntaxTreeNode token)

None	render_image (self, SyntaxTreeNode token)

None	render_span (self, SyntaxTreeNode token)

None	render_front_matter (self, SyntaxTreeNode token)

nodes.field_list	dict_to_fm_field_list (self, dict[str, Any] data, str language_code, int line=0)

None	render_table (self, SyntaxTreeNode token)

None	render_table_row (self, SyntaxTreeNode token)

None	render_s (self, SyntaxTreeNode token)

None	render_math_inline (self, SyntaxTreeNode token)

None	render_math_inline_double (self, SyntaxTreeNode token)

None	render_math_single (self, SyntaxTreeNode token)

None	render_math_block (self, SyntaxTreeNode token)

None	render_math_block_label (self, SyntaxTreeNode token)

None	render_amsmath (self, SyntaxTreeNode token)

None	render_footnote_ref (self, SyntaxTreeNode token)

None	render_footnote_reference (self, SyntaxTreeNode token)

None	render_myst_block_break (self, SyntaxTreeNode token)

None	render_myst_target (self, SyntaxTreeNode token)

None	render_myst_line_comment (self, SyntaxTreeNode token)

None	render_myst_role (self, SyntaxTreeNode token)

None	render_colon_fence (self, SyntaxTreeNode token)

None	render_dl (self, SyntaxTreeNode token)

None	render_field_list (self, SyntaxTreeNode token)

None	render_restructuredtext (self, SyntaxTreeNode token)

None	render_directive (self, SyntaxTreeNode token, str name, str arguments, *dict[str, str]\|None additional_options=None)

list[nodes.Element]	run_directive (self, str name, str first_line, str content, int position, dict[str, str]\|None additional_options=None)

None	render_substitution_inline (self, SyntaxTreeNode token)

None	render_substitution_block (self, SyntaxTreeNode token)

None	render_substitution (self, SyntaxTreeNode token, bool inline)

Public Attributes
	md

	rules

	md_env

	md_options

	document

	current_node

	language_module_rst

	sphinx_env

Protected Member Functions
None	_render_tokens (self, list[Token] tokens)

None	_render_initialise (self)

None	_render_finalise (self)

Static Protected Member Functions
list[int]	_parse_linenos (str emphasize_lines, int num_lines)

Protected Attributes
	_heading_offset

	_level_to_section

	_heading_slugs

	_inventories

Detailed Description

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

Note, this render is not dependent on Sphinx.

Constructor & Destructor Documentation

◆ init()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.__init__	(		self,
		MarkdownIt	parser
	)

Load the renderer (called by ``MarkdownIt``)

Member Function Documentation

◆ getattr()

myst_parser.mdit_to_docutils.base.DocutilsRenderer.__getattr__	(		self,
		str	name
	)

Warn when the renderer has not been setup yet.

◆ _parse_linenos()

list[int] myst_parser.mdit_to_docutils.base.DocutilsRenderer._parse_linenos	(	str	emphasize_lines,
		int	num_lines
	)

staticprotected

Parse the `emphasize_lines` argument.

Raises ValueError if the argument is invalid.

◆ _render_finalise()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer._render_finalise ( self )

protected

Finalise the render of the document.

◆ _render_initialise()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer._render_initialise ( self )

protected

Initialise the render of the document.

◆ _render_tokens()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer._render_tokens	(		self,
		list[Token]	tokens
	)

protected

Render the tokens.

◆ add_line_and_source_path()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.add_line_and_source_path	(		self,
			node,
		SyntaxTreeNode	token
	)

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

◆ add_line_and_source_path_r()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.add_line_and_source_path_r	(		self,
		list[nodes.Element]	nodes_,
		SyntaxTreeNode	token
	)

Copy the line number and document source path to the docutils nodes,
and recursively to all descendants.

◆ blocks_mathjax_processing()

bool myst_parser.mdit_to_docutils.base.DocutilsRenderer.blocks_mathjax_processing ( self )

Only add mathjax ignore classes if using sphinx,
and using the ``dollarmath`` extension, and ``myst_update_mathjax=True``.

◆ copy_attributes()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.copy_attributes	(		self,
		SyntaxTreeNode	token,
		nodes.Element	node,
		Sequence[str]	keys = `("class",)`,
		*dict[str, Callable[[str], Any]] \| None	converters = `None`,
		dict[str, str] \| None	aliases = `None`
	)

Copy attributes on the token to the docutils node.

:param token: the token to copy attributes from
:param node: the node to copy attributes to
:param keys: the keys to copy from the token (after aliasing)
:param converters: a dictionary of converters for the attributes
:param aliases: a dictionary mapping the token key name to the node key name

◆ create_highlighted_code_block()

nodes.Element myst_parser.mdit_to_docutils.base.DocutilsRenderer.create_highlighted_code_block	(		self,
		str	text,
		str \| None	lexer_name,
		bool	number_lines = `False`,
		int	lineno_start = `1`,
		str \| None	source = `None`,
		int \| None	line = `None`,
		type[nodes.Element]	node_cls = `nodes.literal_block`,
		list[int] \| str \| None	emphasize_lines = `None`
	)

Create a literal block with syntax highlighting.

This mimics the behaviour of the `code-block` directive.

In docutils, this directive directly parses the text with the pygments lexer,
whereas in sphinx, the lexer name is only recorded as the `language` attribute,
and the text is lexed later by pygments within the `visit_literal_block`
method of the output format ``SphinxTranslator``.

Note, this function does not add the literal block to the document.

◆ create_warning()

nodes.system_message \| None myst_parser.mdit_to_docutils.base.DocutilsRenderer.create_warning	(		self,
		str	message,
		MystWarnings \| str	subtype,
		*str \| None	wtype = `None`,
		int \| None	line = `None`,
		nodes.Element \| None	append_to = `None`
	)

Generate a warning, logging if it is necessary.

If the warning type is listed in the ``suppress_warnings`` configuration,
then ``None`` will be returned and no warning logged.

◆ current_node_context()

Iterator[None] myst_parser.mdit_to_docutils.base.DocutilsRenderer.current_node_context	(		self,
		nodes.Element	node,
		bool	append = `False`
	)

Context manager for temporarily setting the current node.

◆ dict_to_fm_field_list()

nodes.field_list myst_parser.mdit_to_docutils.base.DocutilsRenderer.dict_to_fm_field_list	(		self,
		dict[str, Any]	data,
		str	language_code,
		int	line = `0`
	)

Render each key/val pair as a docutils ``field_node``.

Bibliographic keys below will be parsed as Markdown,
all others will be left as literal text.

The field list should be at the start of the document,
and will then be converted to a `docinfo` node during the
`docutils.docutils.transforms.frontmatter.DocInfo` transform (priority 340),
and bibliographic keys (or their translation) will be converted to 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}

Also, the 'dedication' and 'abstract' will be placed outside the `docinfo`,
and so will always be shown in the document.

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.

◆ generate_heading_target()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.generate_heading_target	(		self,
		SyntaxTreeNode	token,
		int	level,
		nodes.Element	node,
		nodes.Element	title_node
	)

Generate a heading target, and add it to the document.

◆ get_inventory_matches()

list[inventory.InvMatch] myst_parser.mdit_to_docutils.base.DocutilsRenderer.get_inventory_matches	(		self,
		*str \| None	invs,
		str \| None	domains,
		str \| None	otypes,
		str \| None	target
	)

Return inventory matches.

This will be overridden for sphinx, to use intersphinx config.

Reimplemented in myst_parser.mdit_to_docutils.sphinx_.SphinxRenderer.

◆ nested_render_text()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.nested_render_text	(		self,
		str	text,
		int	lineno,
		bool	inline = `False`,
		None \| nodes.Element	temp_root_node = `None`,
		int	heading_offset = `0`
	)

Render unparsed text (appending to the current node).

:param text: the text to render
:param lineno: the starting line number of the text, within the full source
:param inline: whether the text is inline or block
:param temp_root_node: If set, allow sections to be created as children of this node
:param heading_offset: offset heading levels by this amount

◆ render()

nodes.document myst_parser.mdit_to_docutils.base.DocutilsRenderer.render	(		self,
		Sequence[Token]	tokens,
			options,
		MutableMapping[str, Any]	md_env
	)

Run the render on a token stream.

:param tokens: list on block tokens to render
:param options: params of parser instance
:param md_env: the markdown-it environment sandbox associated with the tokens,
    containing additional metadata like reference info

Reimplemented from markdown_it.renderer.RendererProtocol.

◆ render_amsmath()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_amsmath	(		self,
		SyntaxTreeNode	token
	)

Reimplemented in myst_parser.mdit_to_docutils.sphinx_.SphinxRenderer.

◆ render_children()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_children	(		self,
		SyntaxTreeNode	token
	)

Render the children of a token.

◆ render_colon_fence()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_colon_fence	(		self,
		SyntaxTreeNode	token
	)

Render a div block, with ``:`` colon delimiters.

◆ render_directive()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_directive	(		self,
		SyntaxTreeNode	token,
		str	name,
		str	arguments,
		*dict[str, str] \| None	additional_options = `None`
	)

Render special fenced code blocks as directives.

:param token: the token to render
:param name: the name of the directive
:param arguments: The remaining text on the same line as the directive name.

◆ render_dl()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_dl	(		self,
		SyntaxTreeNode	token
	)

Render a definition list.

◆ render_fence()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_fence	(		self,
		SyntaxTreeNode	token
	)

Render a fenced code block.

◆ render_field_list()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_field_list	(		self,
		SyntaxTreeNode	token
	)

Render a field list.

◆ render_footnote_ref()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_footnote_ref	(		self,
		SyntaxTreeNode	token
	)

Footnote references are added as auto-numbered,
.i.e. `[^a]` is read as rST `[#a]_`

◆ render_footnote_reference()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_footnote_reference	(		self,
		SyntaxTreeNode	token
	)

Despite the name, this is actually a footnote definition, e.g. `[^a]: ...`

◆ render_front_matter()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_front_matter	(		self,
		SyntaxTreeNode	token
	)

Pass document front matter data.

◆ render_heading()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_heading	(		self,
		SyntaxTreeNode	token
	)

Render a heading, e.g. `# Heading`.

◆ render_link()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_link	(		self,
		SyntaxTreeNode	token
	)

Parse `<http://link.com>` or `[text](link "title")` syntax to docutils AST:

- If `myst_all_links_external` is True, forward to `render_link_url`
- If the link token has a class attribute containing `external`,
    forward to `render_link_url`
- If the link is an id link (e.g. `#id`), forward to `render_link_anchor`
- If the link has a schema, and the schema is in `url_schemes` (e.g. `http:`),
  forward to `render_link_url`
- If the link has an `inv:` schema, forward to `render_link_inventory`
- If the link is an autolink/linkify type link, forward to `render_link_url`
- Otherwise, forward to `render_link_internal`

◆ render_link_anchor()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_link_anchor	(		self,
		SyntaxTreeNode	token,
		str	target
	)

Render link token like `[text](#target)`, to a local target.

:target: the target id, e.g. `#target`

◆ render_link_inventory()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_link_inventory	(		self,
		SyntaxTreeNode	token
	)

Create a link to an inventory object.

This assumes the href is of the form `<scheme>:<path>#<target>`.
The path is of the form `<invs>:<domains>:<otypes>`,
where each of the parts is optional, hence `<scheme>:#<target>` is also valid.
Each of the path parts can contain the `*` wildcard, for example:
`<scheme>:key:*:obj#targe*`.
`\*` is treated as a plain `*`.

◆ render_link_path()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_link_path	(		self,
		SyntaxTreeNode	token
	)

Render a link token like `<path:...>`.

Reimplemented in myst_parser.mdit_to_docutils.sphinx_.SphinxRenderer.

◆ render_link_project()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_link_project	(		self,
		SyntaxTreeNode	token
	)

Render a link token like `<project:...>`.

Reimplemented in myst_parser.mdit_to_docutils.sphinx_.SphinxRenderer.

◆ render_link_unknown()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_link_unknown	(		self,
		SyntaxTreeNode	token
	)

Render link token `[text](link "title")`,
where the link has not been identified as an external URL::

    <reference refname="link" title="title">
        text

`text` can contain nested syntax, e.g. `[**bold**](link "title")`.

Note, this is overridden by `SphinxRenderer`, to use `pending_xref` nodes.

Reimplemented in myst_parser.mdit_to_docutils.sphinx_.SphinxRenderer.

◆ render_link_url()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_link_url	(		self,
		SyntaxTreeNode	token,
		None \| UrlSchemeType	conversion = `None`
	)

Render link token (including autolink and linkify),
where the link has been identified as an external URL.

◆ render_math_block_label()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_math_block_label	(		self,
		SyntaxTreeNode	token
	)

Reimplemented in myst_parser.mdit_to_docutils.sphinx_.SphinxRenderer.

◆ render_restructuredtext()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_restructuredtext	(		self,
		SyntaxTreeNode	token
	)

Render the content of the token as restructuredtext.

◆ render_s()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_s	(		self,
		SyntaxTreeNode	token
	)

Render a strikethrough token.

◆ render_span()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_span	(		self,
		SyntaxTreeNode	token
	)

Render an inline span token.

◆ render_substitution()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_substitution	(		self,
		SyntaxTreeNode	token,
		bool	inline
	)

Substitutions are rendered by:

1. Combining global substitutions with front-matter substitutions
   to create a variable context (front-matter takes priority)
2. Add the sphinx `env` to the variable context (if available)
3. Create the string content with Jinja2 (passing it the variable context)
4. If the substitution is inline and not a directive,
   parse to nodes ignoring block syntaxes (like lists or block-quotes),
   otherwise parse to nodes with all syntax rules.

◆ render_substitution_block()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_substitution_block	(		self,
		SyntaxTreeNode	token
	)

Render block substitution {{key}}.

◆ render_substitution_inline()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.render_substitution_inline	(		self,
		SyntaxTreeNode	token
	)

Render inline substitution {{key}}.

◆ renderInlineAsText()

str myst_parser.mdit_to_docutils.base.DocutilsRenderer.renderInlineAsText	(		self,
		list[SyntaxTreeNode]	tokens
	)

Special kludge for image `alt` attributes to conform CommonMark spec.

Don't try to use it! Spec requires to show `alt` content with stripped markup,
instead of simple escaping.

◆ run_directive()

list[nodes.Element] myst_parser.mdit_to_docutils.base.DocutilsRenderer.run_directive	(		self,
		str	name,
		str	first_line,
		str	content,
		int	position,
		dict[str, str] \| None	additional_options = `None`
	)

Run a directive and return the generated nodes.

:param name: the name of the directive
:param first_line: The text on the same line as the directive name.
    May be an argument or body text, dependent on the directive
:param content: All text after the first line. Can include options.
:param position: The line number of the first line
:param additional_options: Additional options to add to the directive,
    above those parsed from the content.

◆ setup_render()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.setup_render	(		self,
		dict[str, Any]	options,
		MutableMapping[str, Any]	env
	)

Setup the renderer with per render variables.

◆ sphinx_env()

BuildEnvironment | None myst_parser.mdit_to_docutils.base.DocutilsRenderer.sphinx_env ( self )

Return the sphinx env, if using Sphinx.

◆ update_section_level_state()

None myst_parser.mdit_to_docutils.base.DocutilsRenderer.update_section_level_state	(		self,
		nodes.section	section,
		int	level
	)

Update the section level state, with the new current section and level.

The documentation for this class was generated from the following file:

docs/help/help-venv/lib/python3.12/site-packages/myst_parser/mdit_to_docutils/base.py

Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ __getattr__()

◆ _parse_linenos()

◆ _render_finalise()

◆ _render_initialise()

◆ _render_tokens()

◆ add_line_and_source_path()

◆ add_line_and_source_path_r()

◆ blocks_mathjax_processing()

◆ copy_attributes()

◆ create_highlighted_code_block()

◆ create_warning()

◆ current_node_context()

◆ dict_to_fm_field_list()

◆ generate_heading_target()

◆ get_inventory_matches()

◆ nested_render_text()

◆ render()

◆ render_amsmath()

◆ render_children()

◆ render_colon_fence()

◆ render_directive()

◆ render_dl()

◆ render_fence()

◆ render_field_list()

◆ render_footnote_ref()

◆ render_footnote_reference()

◆ render_front_matter()

◆ render_heading()

◆ render_link()

◆ render_link_anchor()

◆ render_link_inventory()

◆ render_link_path()

◆ render_link_project()

◆ render_link_unknown()

◆ render_link_url()

◆ render_math_block_label()

◆ render_restructuredtext()

◆ render_s()

◆ render_span()

◆ render_substitution()

◆ render_substitution_block()

◆ render_substitution_inline()

◆ renderInlineAsText()

◆ run_directive()

◆ setup_render()

◆ sphinx_env()

◆ update_section_level_state()

◆ init()

◆ getattr()