Python API

Python API#

Text to docutils AST#

rst_to_myst.parser.to_docutils_ast(text: str, uri: str = 'source', report_level: int = 2, halt_level: int = 4, warning_stream: StringIO | None = None, language_code: str = 'en', use_sphinx: bool = True, extensions: Iterable[str] = (), default_domain: str = 'py', conversions: dict | None = None, front_matter: bool = True, namespace: ApplicationNamespace | None = None) → tuple[docutils.nodes.document, _io.StringIO][source]#

Convert a string of text to a docutils AST.

Parameters:

text – The text to convert.
uri – The URI of the document.
report_level – The report level for docutils.
halt_level – The halt level for docutils.
warning_stream – A stream to write warnings to.
language_code – The language code for docutils.
use_sphinx – Whether to use Sphinx roles and directives.
extensions – A list of Sphinx extensions to use.
default_domain – The default Sphinx domain.
conversions – A dictionary of conversion functions.
front_matter – Whether to treat initial field list as front matter.
namespace – A pre-computed docutils namespace to use.

docutils AST to Markdown-It Tokens#

class rst_to_myst.markdownit.RenderOutput(tokens, env)[source]#

env: dict[str, Any]#: Alias for field number 1

tokens: list[markdown_it.token.Token]#: Alias for field number 0

class rst_to_myst.markdownit.MarkdownItRenderer(document: document, *, warning_stream: IO | None = None, raise_on_warning: bool = False, cite_prefix: str = 'cite_', default_role: str | None = None, colon_fences: bool = True, dollar_math: bool = True)[source]#

Render docutils AST to Markdown-It token stream.

add_token(ttype: str, tag: str, nesting: int, *, content: str = '', **kwargs: Any) → Token[source]#: A markdown-it token to the stream, handling inline tokens and children.

default_departure(node)[source]#: Override for generic, uniform traversals.

default_visit(node)[source]#: Override for generic, uniform traversals.

parse_gfm_table(node) → bool[source]#

Check whether an RST table can be converted to a GFM one.

RST tables can have e.g. cells spanning multiple columns/rows, which the GitHub Flavoured Markdown (GFM) table variant does not support.

to_tokens() → RenderOutput[source]#: Reset tokens and convert full document.

unknown_departure(node)[source]#

Called before exiting unknown Node types.

Raise exception unless overridden.

unknown_visit(node)[source]#

Called when entering unknown Node types.

Raise an exception unless overridden.

Markdown-It Tokens to Text#

rst_to_myst.mdformat_render.from_tokens(output: RenderOutput, *, consecutive_numbering: bool = True, warning_stream: IO | None = None) → str[source]#: Convert markdown-it tokens to text.

Full Conversion#

class rst_to_myst.mdformat_render.ConvertedOutput(text: str, tokens: list[markdown_it.token.Token], env: dict[str, Any], warning_stream: IO, extensions: set[str])[source]#

Output from rst_to_myst.

env: dict[str, Any]#: Alias for field number 2

extensions: set[str]#: Alias for field number 4

text: str#: Alias for field number 0

tokens: list[markdown_it.token.Token]#: Alias for field number 1

warning_stream: IO#: Alias for field number 3

rst_to_myst.mdformat_render.rst_to_myst(text: str, *, warning_stream: IO | None = None, language_code='en', use_sphinx: bool = True, extensions: Iterable[str] = (), conversions: dict[str, str] | None = None, default_domain: str = 'py', default_role: str | None = None, raise_on_warning: bool = False, cite_prefix: str = 'cite_', consecutive_numbering: bool = True, colon_fences: bool = True, dollar_math: bool = True) → ConvertedOutput[source]#

Convert RST text to MyST Markdown text.