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: Optional[StringIO] = None, language_code: str = 'en', use_sphinx: bool = True, extensions: Iterable[str] = (), default_domain: str = 'py', conversions: Optional[dict] = None, front_matter: bool = True, namespace: Optional[ApplicationNamespace] = None) Tuple[document, 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]#
property env#

Alias for field number 1

property tokens#

Alias for field number 0

class rst_to_myst.markdownit.MarkdownItRenderer(document: document, *, warning_stream: Optional[IO] = None, raise_on_warning: bool = False, cite_prefix: str = 'cite_', default_role: Optional[str] = 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: Optional[IO] = None) str[source]#

Convert markdown-it tokens to text.

Full Conversion#

class rst_to_myst.mdformat_render.ConvertedOutput(text: str, tokens: List[Token], env: Dict[str, Any], warning_stream: IO, extensions: Set[str])[source]#

Output from rst_to_myst.

property env#

Alias for field number 2

property extensions#

Alias for field number 4

property text#

Alias for field number 0

property tokens#

Alias for field number 1

property warning_stream#

Alias for field number 3

rst_to_myst.mdformat_render.rst_to_myst(text: str, *, warning_stream: Optional[IO] = None, language_code='en', use_sphinx: bool = True, extensions: Iterable[str] = (), conversions: Optional[Dict[str, str]] = None, default_domain: str = 'py', default_role: Optional[str] = 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.

Parameters:
  • text – The input RST text

  • warning_stream – The warning IO to write to

  • language_code – the language module to use, for directive/role name translation

  • use_sphinx – Whether to load sphinx roles, directives and extentions

  • extensions – Sphinx extension to load

  • conversions – Overrides for mapping of how to convert directives; directive module path -> conversion type

  • default_domain – name of the default sphinx domain

  • default_role – name of the default role, otherwise convert to a literal

  • cite_prefix – Prefix to add to citation references

  • raise_on_warning – Raise exception on parsing warning

  • consecutive_numbering – Apply consecutive numbering to ordered lists

  • colon_fences – Use colon fences for directives with parsed content

  • dollar_math – Convert math (where possible) to dollar-delimited math