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 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

Other package managers (and thanks to the people who maintain them)

rich-rst is packaged by volunteers across many ecosystems. A huge thank you to everyone listed below for keeping it available. Distro packages may lag behind PyPI; see Repology for current versions.

Package manager	Package	Maintainer(s)	Install
PyPI	rich-rst	Wasi Master	pip install rich-rst
conda-forge	rich-rst	David Brochart	conda install -c conda-forge rich-rst
Alpine Linux	py3-rich-rst	Bart Ribbers	apk add py3-rich-rst
ALT Linux	python3-module-rich-rst	Vladislav Eliseev	apt-get install python3-module-rich-rst
Arch Linux (AUR)	python-rich-rst	demizer	yay -S python-rich-rst
Debian / Ubuntu also Kali, Parrot, Raspbian, Devuan, PureOS, deepin	python-rich-rst	Nilson F. Silva & the Debian Python Team	sudo apt install python3-rich-rst
Exherbo	dev-python/rich-rst	Timo Gurr	cave resolve dev-python/rich-rst
Fedora	python-rich-rst	Sam Doran	sudo dnf install python3-rich-rst
FreeBSD	textproc/py-rich-rst	Po-Chuan Hsieh (sunpoet)	cd /usr/ports/textproc/py-rich-rst && make install clean
Gentoo (GURU)	dev-python/rich-rst	Florian Albrechtskirchinger	eselect repository enable guru && emerge dev-python/rich-rst
GNU Guix	python-rich-rst	Guix contributors	guix install python-rich-rst
MacPorts	py-rich_rst	Unmaintained (open for adoption)	sudo port install py313-rich_rst
Mageia	python-rich-rst	papoteur	sudo dnf install python3-rich-rst
Nixpkgs	python3Packages.rich-rst	Nixpkgs contributors (originally Joel Koen)	nix-shell -p python3Packages.rich-rst
openSUSE	python-rich-rst	Martin Pluskal & the openSUSE Python team	sudo zypper install python313-rich-rst

Packaging rich-rst somewhere not listed here, or spotted a mistake? Open an issue or PR so you can be credited.

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, admonition_style, and allow_file_access.

Directives that read other files (include, literalinclude, and raw/csv-table with :file: or :url:) are disabled by default. Pass allow_file_access=True to enable them, but only for markup you trust.

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, --allow-file-access, --admonition-style, -S/--save-html, --html-theme, --list-html-themes, --output, --debug, 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.

Documentation

• Project documentation
• Extension API guide
• Source code
• Issue tracker

Changelog

See CHANGELOG.md.