API Reference

Python API

For visitor- and plugin-style customization, see Extension API.

The main class is RestructuredText. Several aliases are provided for convenience; they are identical:

Name	Import path
RestructuredText	from rich_rst import RestructuredText
ReStructuredText	from rich_rst import ReStructuredText
reStructuredText	from rich_rst import reStructuredText
RST	from rich_rst import RST
reST	from rich_rst import reST

class rich_rst.RestructuredText(markup: str, code_theme: str | SyntaxTheme | None = 'monokai', show_errors: bool | None = True, guess_lexer: bool | None = False, default_lexer: str | None = 'python', sphinx_compat: bool | None = True, filename: str | None = '<rst-document>')

A reStructuredText renderable for rich.

Parameters:

• markup (str) – A string containing reStructuredText markup.

• code_theme (Optional[Union[str, SyntaxTheme]]) – Pygments theme for code blocks. Defaults to “monokai”.

• show_errors (Optional[bool]) – Whether to show system_messages aka errors and warnings.

• guess_lexer (Optional[bool]) – Whether to guess lexers for code blocks without specified language.

• default_lexer (Optional[str]) – Which lexer to use if no lexer is guessed or found. Defaults to “python”

• sphinx_compat (Optional[bool]) – Enable compatibility with Sphinx roles (func, meth, class, etc.) commonly used in Python docstrings. When enabled, these roles render as inline code instead of errors. Defaults to True for better compatibility with Python documentation.

• filename (Optional[str]) – A file name to use for error messages, useful for debugging purposes. Defaults to “<rst-document>”

Command-line interface

rich-rst ships with a CLI module that renders RST files (or stdin) directly to the terminal.

Usage

python -m rich_rst PATH [options]
python -m rich_rst - [options]     # read from stdin

PATH is required unless you use --list-html-themes.

Options

Flag	Description
-c, --force-color	Force ANSI colour output even on non-terminal streams.
--version	Show the installed package version and exit.
-e, --encoding	File encoding (default: utf-8).
-w, --width	Output width in columns (auto-detected by default).
-hw, --html-width	max-width applied when saving HTML output (default: 1675px).
-t, --code-theme	Pygments theme used for syntax-highlighted code blocks (default: monokai).
--show-line-numbers	Show line numbers in syntax-highlighted code blocks.
-html, --save-html	Path to save the rendered output as an HTML file.
-r, --wrap	Hard-wrap long lines.
-s, --soft-wrap	Enable soft-wrap mode (lines are wrapped by the terminal).
-gl, --guess-lexer	Guess the syntax-highlighting language for code blocks that do not specify one.
-dl, --default-lexer	Fallback language for code blocks when none is detected (default: python).
-se, --show-errors	Show RST parse errors and warnings.
--html-theme	Theme for --save-html output. Available values: dracula, monokai, night-owl, dimmed-monokai, default.
--list-html-themes	Print available HTML themes and exit.
-o, --output	Write rendered plain-text output to a file instead of stdout.