RST Rendering

[ashwin153]

It would be really cool if Rich supported RST in the same way that it supports Markdown. I have a defopt CLI that I currently document using plain-text docstrings; however, it would be really cool if I could instead use RST to document my CLI and rely on Rich to correctly render it. Just like Markdown support, RST support wouldn't need to be complete; I think focusing on the low hanging fruit (e.g., code-block, headers, italics, bold, lists) would satisfy most common use-cases. What do you think? Would love to help working on it if you see value in the idea.

[willmcgugan]

I don't have any plans for RST support, but it would be nice to have. Probably as an external package, i.e. rich-rst. If you tackle it, I'd be happy to help.

[ashwin153]

My plan is to create a docutils.writers.Writer implementation that uses Rich to render RST documents in the console. I think it makes sense for the implementation to live in rst.py within rich itself, but I'm fine with trying to upstream it into docutils or creating a separate package if you think that's better. https://github.com/docutils-mirror/docutils/issues/19

[ashwin153]

Here's a simple implementation I've been playing around with.

import docutils.io
import docutils.nodes
import docutils.parsers.rst
import docutils.utils

from rich.console import Console, ConsoleOptions, RenderResult
from rich.jupyter import JupyterMixin
from rich.syntax import Syntax
from rich.text import Text


class RSTVisitor(docutils.nodes.SparseNodeVisitor):
    """A reStructuredText to Rich converter.

    Args:
        document (docutils.nodes.document): RST document to convert.
    """

    def __init__(
        self,
        document: docutils.nodes.document,
    ) -> None:
        super().__init__(document)
        self.renderables = []

    def depart_paragraph(self, node):
        self.renderables.append(Text())

    def visit_Text(self, node):
        self.renderables.append(Text(node.astext(), end=""))

    def visit_emphasis(self, node):
        self.renderables.append(Text(node.astext(), style="italic", end=""))
        raise docutils.nodes.SkipChildren()

    def visit_strong(self, node):
        self.renderables.append(Text(node.astext(), style="bold", end=""))
        raise docutils.nodes.SkipChildren()

    def visit_literal(self, node):
        self.renderables.append(Syntax(node.astext(), "python", code_width=len(node.astext())))
        raise docutils.nodes.SkipChildren()

    def visit_bullet_list(self, node):
        for list_item in node.children:
            self.renderables.append(Text("• ", end=""))
            self.renderables.append(Text(list_item.astext()))

        self.renderables.append(Text())
        raise docutils.nodes.SkipChildren()

    def visit_enumerated_list(self, node):
        for i, list_item in enumerate(node.children):
            self.renderables.append(Text(f"{i+1}. ", end=""))
            self.renderables.append(Text(list_item.astext()))

        self.renderables.append(Text())
        raise docutils.nodes.SkipChildren()

    def visit_literal_block(self, node):
        lexer = node["classes"][1] if len(node["classes"]) >= 2 else "python"
        self.renderables.append(Syntax(node.astext(), lexer))
        raise docutils.nodes.SkipChildren()


class RST(JupyterMixin):
    """A reStructuredText renderable.

    Args:
        markup (str): A string containing RST.
    """

    def __init__(
        self,
        markup: str,
    ) -> None:
        self.markup = markup

    def __rich_console__(
        self,
        console: Console,
        options: ConsoleOptions,
    ) -> RenderResult:
        # Parse the `markup` into a RST `document`.
        option_parser = docutils.frontend.OptionParser(components=(docutils.parsers.rst.Parser,))
        settings = option_parser.get_default_values()
        source = docutils.io.StringInput(self.markup)
        document = docutils.utils.new_document(source.source_path, settings)
        rst_parser = docutils.parsers.rst.Parser()
        rst_parser.parse(source.read(), document)

        # Render the RST `document` using Rich.
        visitor = RSTVisitor(document)
        document.walkabout(visitor)

        for renderable in visitor.renderables:
            yield from console.render(renderable, options)

Here's what it can do so far.

import rich


INPUT = """
*Italic*
**Bold**
``code``

- a
- b
- c

#. a
#. b
#. c

.. code-block:: python

    if x:
        print("Hello, World!")
"""

rich.print(RST(INPUT))

Let me know what you think.

[ashwin153]

Another option is to use a library like https://github.com/sixty-north/rst_to_md to convert RST to Markdown, and then just use the built-in Markdown rendering. What do you think about that approach?

[willmcgugan]

Looks like a good approach. I suspect the better solution is something like your implementation with docutils. I don't think there is a 1-1 translation for RST and Markdown so the conversion approach would probably loose something.

[wasi-master]

So for future visitors of this discussion, I've made a library called rich-rst, inspired code from by this comment. And @ashwin153, please tell me if you have any issues with me using your code as a starting point, I have given appropriate attribution. :)

[willmcgugan]

@wasi-master I'm planning on using rich-rst with rich-cli!

[wasi-master]

@willmcgugan 😮 then I'll make sure to maintain it as best as I can 😄

[ashwin153]

Please use it, and thanks for offering to maintain this!

[wasi-master]

@ashwin153 Thanks 🤎

[wasi-master]

So I've released version 1.1.0 of rich-rst with support for a lot more elements and custom styling. I need to write some documentation but the core things are ready. It can't yet show tables. but it does work for most other reStructuredText elements. There are some elements in rst that are not well documented and therefore they aren't supported yet but most of the time it has some fallbacks so users can have a great experience