search

ewels / rich-click

Format click help output nicely with rich.
https://ewels.github.io/rich-click/
MIT License
628 stars 37 forks source link

rich markup shows when using sphinx-click #48

Open ri0t opened 2 years ago

ri0t commented 2 years ago

Currently, the click-man-page rendering and sphinx html docs get pretty messed up when using rich-click. Here's an example of a man page output:

ISO(1)                                        iso Manual                                       ISO(1)

NAME
       iso - Main Isomer CLI

SYNOPSIS
       iso [OPTIONS] COMMAND [ARGS]...

DESCRIPTION
       [bold cyan on blue] :diamonds: Isomer[/][white on blue] Management Tool [/]

       This tool supports various operations to manage Isomer instances.

       [yellow]  :warning: Most of the commands are [u]grouped[/u].[/]

       To obtain more information about the groups' available subcommands/groups, try:

       [bright_cyan]  iso [/]

       To display details of a command or its subgroups, try:

       [bright_cyan]  iso   [..]  --help[/]

       To get a map of all available commands, try:

       [bright_cyan]  iso cmdmap[/]

OPTIONS
       -e, --env, --environment [blue|green|current|other]
              Override environment to act on (CAUTION!)

Notice the --env option - it is not immediately obvious if that is weird markup or actual option choices.

I think it would make sense to somehow throw all the markup out in manpages. With sphinx-generated html or similar things that could render them - not sure how to proceed.

ewels commented 2 years ago

Hmm, I've not heard of click-man-page before, and I guess it's the sphinx-click plugin? I'd need to look into how they are fetching the click output first - if you're able to do some detective work that would help.

However, hopefully https://github.com/ewels/rich-click/issues/19 will help. The aim there is to make it easier to return a rich renderable object instead of always printing. Then it would be fairly easy to get a plaintext copy of the help without any markup. If the above plugins are using regular click function calls to fetch the help strings, it might be that we can refactor the rich-click code to better emulate native click. Bit of a long shot, but may be possible.

dwreeves commented 7 months ago

As far as rst is concerned, we have it on our roadmap to support rst docstrings in #172.

And HTML generation is supported via: rich-click --output=html path.to.my:cli --help

Rendering the CLI help text as simple rst is a different story. We can potentially add this to the --output=? options in the rich-click CLI.

I don't know how high of a priority this is. Typer has a markdown rendering feature and I suppose it would be cool to keep up with them in terms of features. I'm marking this as being on the 1.9 roadmap but it's low on the 1.9 wishlist.