rich-rst

Tests Status CodeQL Status Codecov

Render reStructuredText with Rich. This package turns reST documents into Rich renderables so you can preview documentation, docstrings, and snippets directly in the terminal. Also includes a CLI.

Highlights

Supports all currently documented RST elements.
Handles common documentation features such as headings, lists, tables, links, images, code blocks, footnotes, and many Sphinx roles.
Provides both a Python API and a command-line interface.
Can also export rendered output to HTML from the CLI.

Installation

pip install rich-rst

Python API

from rich import print
from rich_rst import RestructuredText

document = """
rich-rst
========

This is a **test** document.

- Item one
- Item two

.. code-block:: python

   print("hello")
"""

print(RestructuredText(document))

The main constructor options are code_theme, show_line_numbers, show_errors, guess_lexer, default_lexer, sphinx_compat, and admonition_style.

Command Line Interface

Render a file:

python -m rich_rst readme.rst

Render from standard input:

python -m rich_rst -

View all available options:

python -m rich_rst --help

Useful flags include --code-theme, --show-line-numbers, --guess-lexer, --default-lexer, --show-errors, --admonition-style, --save-html, --html-theme, --list-html-themes, --output, and --version.

Compatibility

The renderer is designed for terminal output, so not every docutils feature can be represented visually. The current limitations and unsupported elements are documented in ELEMENTS.md.