all2md.options.rst

Configuration options for reStructuredText parsing and rendering.

This module defines options for rST document conversion.

class all2md.options.rst.RstParserOptions

Bases: BaseParserOptions

Configuration options for reStructuredText-to-AST parsing.

This dataclass contains settings specific to parsing reStructuredText documents into AST representation using docutils.

Parameters:

  • strict_mode (bool, default False) – Whether to raise errors on invalid RST syntax. When False, attempts to recover gracefully.

  • parse_admonitions (bool, default True) – Whether to parse RST admonitions (note, warning, tip, important, etc.). When True, admonitions are converted to BlockQuote nodes with metadata indicating the admonition type. When False, admonitions are skipped.

  • strip_comments (bool, default False) – Whether to strip comments from the output. When True, RST comments are removed completely. When False, comments are preserved as Comment AST nodes with metadata.

Notes

RST directives are always processed by docutils. Directive types like code-block, image, and math are converted to their corresponding AST nodes. Admonitions (note, warning, tip, etc.) are converted to BlockQuote nodes with metadata when parse_admonitions=True.

strict_mode: bool = False
parse_admonitions: bool = True
strip_comments: bool = False
__init__(extract_metadata: bool = False, strict_mode: bool = False, parse_admonitions: bool = True, strip_comments: bool = False) → None
class all2md.options.rst.RstRendererOptions

Bases: BaseRendererOptions

Configuration options for AST-to-reStructuredText rendering.

This dataclass contains settings for rendering AST documents as reStructuredText output.

Parameters:

  • heading_chars (str, default "=-~^*") – Characters to use for heading underlines from h1 to h5. First character is for level 1, second for level 2, etc.

  • table_style ({"grid", "simple"}, default "grid") – Table rendering style: - “grid”: Grid tables with +—+ borders - “simple”: Simple tables with === separators

  • code_directive_style ({"double_colon", "directive"}, default "directive") – Code block rendering style: - “double_colon”: Use ::, literal blocks - “directive”: Use .. code-block::, directive

  • line_length (int, default 80) – Target line length for wrapping text.

  • hard_line_break_mode ({"line_block", "raw"}, default "line_block") – How to render hard line breaks: - “line_block”: Use RST line block syntax (pipe prefix), the standard approach - “raw”: Use plain newline, less faithful but simpler in complex containers

  • hard_line_break_fallback_in_containers (bool, default True) – Automatically fallback to raw mode for line breaks inside lists or blockquotes. When True, prevents semantic changes from line block syntax in containers. When False, always uses the configured hard_line_break_mode.

  • comment_mode ({"comment", "note", "ignore"}, default "comment") – How to render Comment and CommentInline AST nodes: - “comment”: Render as rST comments (.. Comment text) - “note”: Render as .. note:: directive blocks (visible annotations) - “ignore”: Skip comment nodes entirely This controls presentation of comments from source documents.

Notes

Text Escaping:

Special RST characters (asterisks, underscores, backticks, brackets, pipes, colons, angle brackets) are automatically escaped in text nodes to prevent unintended formatting.

Line Breaks:

Hard line breaks behavior depends on the hard_line_break_mode option:

  • line_block mode (default): Uses RST line block syntax (pipe prefix). This is the standard RST approach for preserving line structure. May be surprising inside complex containers like lists and block quotes as it changes semantic structure.

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

Soft line breaks always render as spaces, consistent with RST paragraph semantics.

Recommendation: Use “raw” mode if line blocks cause formatting issues in lists or nested structures. Use “line_block” (default) for maximum RST fidelity.

Unsupported Features:

  • Strikethrough: RST has no native strikethrough syntax. Content renders as plain text.

  • Underline: RST has no native underline syntax. Content renders as plain text.

  • Superscript/Subscript: Rendered using RST role syntax (:sup: and :sub:).

Table Limitations:

Both grid and simple table styles do not support multi-line content within cells. Cell content must be single-line text. Complex cell content (multiple paragraphs, nested lists) will be rendered inline, which may cause formatting issues.

heading_chars: str = '=-~^*'
table_style: Literal['grid', 'simple'] = 'grid'
code_directive_style: Literal['double_colon', 'directive'] = 'directive'
line_length: int = 80
hard_line_break_mode: Literal['line_block', 'raw'] = 'line_block'
hard_line_break_fallback_in_containers: bool = True
comment_mode: Literal['comment', 'note', 'ignore'] = 'comment'
__init__(fail_on_resource_errors: bool = False, max_asset_size_bytes: int = 52428800, metadata_policy: MetadataRenderPolicy = <factory>, creator: str | None = 'all2md', heading_chars: str = '=-~^*', table_style: RstTableStyle = 'grid', code_directive_style: RstCodeStyle = 'directive', line_length: int = 80, hard_line_break_mode: RstLineBreakMode = 'line_block', hard_line_break_fallback_in_containers: bool = True, comment_mode: RstCommentMode = 'comment') → None