all2md.renderers.rst

reStructuredText rendering from AST.

This module provides the RestructuredTextRenderer class which converts AST nodes to reStructuredText. The renderer supports configurable heading underlines, table styles, and code block formatting.

The rendering process uses the visitor pattern to traverse the AST and generate RST output.

class all2md.renderers.rst.RestructuredTextRenderer

Bases: NodeVisitor, InlineContentMixin, BaseRenderer

Render AST nodes to reStructuredText.

This class implements the visitor pattern to traverse an AST and generate RST output with configurable formatting options.

Parameters:: options (RstRendererOptions or None, default = None) – RST formatting options

Examples

Basic usage:

>>> from all2md.options.rst import RstRendererOptions
>>> from all2md.ast import Document, Heading, Text
>>> from all2md.renderers.rst import RestructuredTextRenderer
>>> doc = Document(children=[
...     Heading(level=1, content=[Text(content="Title")])
... ])
>>> renderer = RestructuredTextRenderer()
>>> rst = renderer.render_to_string(doc)
>>> print(rst)
Title
=====

Initialize the RST renderer with options.

__init__(options: RstRendererOptions | None = None): Initialize the RST renderer with options.

render_to_string(document: Document) → str

Render a document AST to RST string.

Parameters:: document (Document) – The document node to render
Returns:: RST text
Return type:: str

visit_document(node: Document) → None

Render a Document node.

Parameters:: node (Document) – Document to render

visit_heading(node: Heading) → None

Render a Heading node.

Parameters:: node (Heading) – Heading to render

visit_paragraph(node: Paragraph) → None

Render a Paragraph node.

Parameters:: node (Paragraph) – Paragraph to render

visit_code_block(node: CodeBlock) → None

Render a CodeBlock node.

Parameters:: node (CodeBlock) – Code block to render

visit_block_quote(node: BlockQuote) → None

Render a BlockQuote node.

Parameters:: node (BlockQuote) – Block quote to render

visit_list(node: List) → None

Render a List node.

Parameters:: node (List) – List to render

visit_list_item(node: ListItem) → None

Render a ListItem node.

Parameters:: node (ListItem) – List item to render

visit_table(node: Table) → None

Render a Table node.

Parameters:: node (Table) – Table to render

visit_table_row(node: TableRow) → None

Render a TableRow node.

Parameters:: node (TableRow) – Table row to render

visit_table_cell(node: TableCell) → None

Render a TableCell node.

Parameters:: node (TableCell) – Table cell to render

visit_thematic_break(node: ThematicBreak) → None

Render a ThematicBreak node.

Parameters:: node (ThematicBreak) – Thematic break to render

visit_text(node: Text) → None

Render a Text node.

Parameters:: node (Text) – Text to render

visit_emphasis(node: Emphasis) → None

Render an Emphasis node.

Parameters:: node (Emphasis) – Emphasis to render

visit_strong(node: Strong) → None

Render a Strong node.

Parameters:: node (Strong) – Strong to render

visit_code(node: Code) → None

Render a Code node.

Parameters:: node (Code) – Code to render

visit_link(node: Link) → None

Render a Link node.

Parameters:: node (Link) – Link to render

visit_image(node: Image) → None

Render an Image node.

Parameters:: node (Image) – Image to render

visit_line_break(node: LineBreak) → None

Render a LineBreak node.

Soft line breaks render as spaces to maintain paragraph flow. Hard line breaks rendering depends on the hard_line_break_mode option.

Parameters:: node (LineBreak) – Line break to render

Notes

RST does not have a direct equivalent to hard line breaks within paragraphs.

line_block mode (default): Uses line block syntax with pipe prefix, which is the idiomatic RST approach for preserving explicit line breaks. May change semantic structure in complex containers like lists.

raw mode: Uses plain newlines. Less faithful to RST but simpler in complex containers. May not preserve visual breaks in all RST processors.

Automatic fallback: When hard_line_break_fallback_in_containers is True and we’re inside a list or blockquote, automatically uses raw mode to prevent semantic changes from line block syntax.

visit_definition_list(node: DefinitionList) → None

Render a DefinitionList node.

Parameters:: node (DefinitionList) – Definition list to render

visit_definition_term(node: DefinitionTerm) → None

Render a DefinitionTerm node.

Parameters:: node (DefinitionTerm) – Definition term to render

visit_definition_description(node: DefinitionDescription) → None

Render a DefinitionDescription node.

Parameters:: node (DefinitionDescription) – Definition description to render

visit_strikethrough(node: Strikethrough) → None

Render a Strikethrough node as plain text.

Parameters:: node (Strikethrough) – Strikethrough node to render

Notes

reStructuredText has no native strikethrough syntax. Content is rendered as plain text without any special formatting. This is the standard fallback for unsupported inline formatting in RST.

visit_underline(node: Underline) → None

Render an Underline node as plain text.

Parameters:: node (Underline) – Underline node to render

Notes

reStructuredText has no native underline syntax for inline text. Content is rendered as plain text without any special formatting. This is the standard fallback for unsupported inline formatting in RST.

visit_superscript(node: Superscript) → None

Render a Superscript node using RST role syntax.

Parameters:: node (Superscript) – Superscript node to render

Notes

Uses RST’s :sup: interpreted text role for superscript formatting. This requires Docutils or Sphinx for proper rendering.

visit_subscript(node: Subscript) → None

Render a Subscript node using RST role syntax.

Parameters:: node (Subscript) – Subscript node to render

Notes

Uses RST’s :sub: interpreted text role for subscript formatting. This requires Docutils or Sphinx for proper rendering.

visit_html_inline(node: HTMLInline) → None: Render inline HTML (preserve as-is).

visit_html_block(node: HTMLBlock) → None: Render HTML block (preserve as-is).

visit_footnote_reference(node: FootnoteReference) → None: Render footnote reference.

visit_footnote_definition(node: FootnoteDefinition) → None: Render footnote definition.

visit_math_inline(node: MathInline) → None: Render inline math.

visit_math_block(node: MathBlock) → None: Render math block.

visit_comment(node: Comment) → None

Render a Comment node (block-level).

Parameters:: node (Comment) – Comment block to render

Notes

Renders as RST comment using the .. syntax with indented content. Each line of the comment content is indented with 3 spaces.

visit_comment_inline(node: CommentInline) → None

Render a CommentInline node (inline).

Parameters:: node (CommentInline) – Inline comment to render

Notes

RST does not have native inline comments. This method falls back to HTML comment syntax for inline comments, which is supported by RST processors.

render(doc: Document, output: str | Path | IO[bytes]) → None

Render AST to RST and write to output.

Parameters:

doc (Document) – AST Document node to render
output (str, Path, or IO[bytes]) – Output destination (file path or file-like object)