Rich markup in generated Markdown docs

[tiangolo]

Discussed in #818

^{Originally posted by tiangolo May 2, 2024}

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the Typer documentation, with the integrated search.
• I already searched in Google "How to X in Typer" and didn't find any information.
• I already read and followed all the tutorials in the docs and didn't find an answer.
• I already checked if it is not related to Typer but to Click.

Commit to Help

• I commit to help with one of those options 👆

Example Code

import typer
from typing_extensions import Annotated

app = typer.Typer(rich_markup_mode="rich")


@app.command()
def hello(
    name: Annotated[
        str, typer.Option(help="The [bold]cool[/bold] name of the [green]user[/green]")
    ],
):
    print(f"Hello {name}")


if __name__ == "__main__":
    app()

Description

• Create this script in main.py
• Generate a README with typer main.py utils docs --output demo.md

The output is:

# `hello`

**Usage**:

```console
$ hello [OPTIONS]
```

**Options**:

* `--name TEXT`: The [bold]cool[/bold] name of the [green]user[/green]  [required]
* `--install-completion`: Install completion for the current shell.
* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
* `--help`: Show this message and exit.

It includes the sections with [green[user[/green] verbatim, those are rendered by Rich in the terminal, but not in the generated Markdown, they look like this:

Rendered Markdown

hello

Usage:

$ hello [OPTIONS]

Options:

• --name TEXT: The [bold]cool[/bold] name of the [green]user[/green] [required]
• --install-completion: Install completion for the current shell.
• --show-completion: Show completion for the current shell, to copy it or customize the installation.
• --help: Show this message and exit.

It might be possible to generate the HTML that would be rendered by Markdown for those sections with Rich's export_html() or maybe export_text(). Not sure but might work.

Operating System

Linux, Windows, macOS

Operating System Details

I tried it on Linux but it's independent of OS.

Typer Version

Typer version: 0.12.3

Python Version

any

Additional Context

No response

[svlandeg]

Update: working on this and definitely seems feasible, current rendering on my branch:

This is using export_html with a custom HTML template. There's still an issue with escaping non-Rich tags like [required], which I'm looking into now.

Hope to get the PR in good shape next week!

[Update]: fixed the required bit: