Render doc comment markdown in help commands

Target component

• CLI
• SDK
• Something else
• Not sure

Overview

We support writing doc comments in markdown and we render said markdown beautifully on the docs site. When printed on the CLI, it is printed as plain text. It would be really snazzy and probably not very difficult to pipe that output through a simple markdown renderer.

Doc comment markdown rendered on the docs site

oxide help completion output

Implementation details

It doesn't look like Rust has a mature equivalent to the wonderful glow, but it looks like there are options, like termimad. On the other hand, if we want to use very popular libraries, the best way might be to use one crate that renders markdown to HTML, like markdown.rs or comrak, and then some other crate to render (or really just strip down) that HTML for the terminal.

The hard part here seems to be hooking into clap to process all help commands in a general way, including oxide help, oxide -h, oxide instance help list, etc. Something on this page of the clap docs will probably help.

Start with the CLI help entry points described in the issue: oxide help, oxide -h, and nested commands such as oxide instance help list. Read clap's Command::help_template documentation and compare the proposed Rust markdown-rendering options. Done means doc-comment markdown is rendered consistently across all help commands rather than printed as plain text.