https://github.com/wasi-master/rich-rst
A reStructuredText renderer for rich
https://github.com/wasi-master/rich-rst
cli command-line-interface docutils python python3 restructuredtext rich rst sphinx
Last synced: 21 days ago
JSON representation
A reStructuredText renderer for rich
- Host: GitHub
- URL: https://github.com/wasi-master/rich-rst
- Owner: wasi-master
- License: mit
- Created: 2022-02-05T13:13:32.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-04-30T08:08:12.000Z (about 2 years ago)
- Last Synced: 2024-10-29T02:18:42.970Z (over 1 year ago)
- Topics: cli, command-line-interface, docutils, python, python3, restructuredtext, rich, rst, sphinx
- Language: HTML
- Homepage: https://rich-rst.readthedocs.io/en/latest/
- Size: 472 KB
- Stars: 14
- Watchers: 3
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# rich-rst
[](https://rich-rst.readthedocs.io/en/latest/?badge=latest)
Render [reStructuredText](https://docutils.sourceforge.io/rst.html) with [Rich](https://rich.readthedocs.io/en/latest/). 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
```sh
pip install rich-rst
```
## Python API
```python
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:
```sh
python -m rich_rst readme.rst
```
Render from standard input:
```sh
python -m rich_rst -
```
View all available options:
```sh
python -m rich_rst --help
```
Useful flags include `--code-theme`, `--show-line-numbers`, `--guess-lexer`, `--default-lexer`, `--show-errors`, `--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](ELEMENTS.md).
## Documentation
- [Project documentation](https://rich-rst.readthedocs.io/en/latest/)
- [Extension API guide](https://rich-rst.readthedocs.io/en/latest/extension_api.html)
- [Source code](https://github.com/wasi-master/rich-rst)
- [Issue tracker](https://github.com/wasi-master/rich-rst/issues)
## Changelog
See [CHANGELOG.md](CHANGELOG.md).