rich-rst

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 89 of the 98 documented docutils elements. See ELEMENTS.md for the full support matrix.
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, and sphinx_compat.

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, --hide-errors, and --save-html.

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.