Bug: commands are always `bold cyan` and a few more style bugs.

[Daniel Reeves]

Overview of issue

Context: I was preparing to draft API documentation.

I was thinking a good way to do API documentation would be to strip all the formatting and only color one thing at a time (e.g. with red) so that the API documentation could clearly show one format at a time.

(Another more complex, but potentially interesting path, for API documentation would be to create an interactive widget along these same principles. 👀)

In any case, here is the code I was messing around with:

import rich_click as click

click.rich_click.STYLE_OPTION = ""
click.rich_click.STYLE_ARGUMENT = ""
click.rich_click.STYLE_COMMAND = ""
click.rich_click.STYLE_SWITCH = ""
click.rich_click.STYLE_METAVAR = ""
click.rich_click.STYLE_METAVAR_APPEND = ""
click.rich_click.STYLE_METAVAR_SEPARATOR = ""
click.rich_click.STYLE_HEADER_TEXT = ""
click.rich_click.STYLE_FOOTER_TEXT = ""
click.rich_click.STYLE_USAGE = ""
click.rich_click.STYLE_USAGE_COMMAND = ""
click.rich_click.STYLE_DEPRECATED = ""
click.rich_click.STYLE_HELPTEXT_FIRST_LINE = ""
click.rich_click.STYLE_HELPTEXT = ""
click.rich_click.STYLE_OPTION_HELP = ""
click.rich_click.STYLE_OPTION_DEFAULT = ""
click.rich_click.STYLE_OPTION_ENVVAR = ""
click.rich_click.STYLE_REQUIRED_SHORT = ""
click.rich_click.STYLE_REQUIRED_LONG = ""
click.rich_click.STYLE_OPTIONS_PANEL_BORDER = ""
click.rich_click.ALIGN_OPTIONS_PANEL = "left"


@click.group()
@click.argument(
    "foo",
    type=click.FLOAT
)
@click.option(
    "--bar",
    default=3,
    show_default="someval",
    type=click.INT,
    help="Lorem ipsum",
    required=False)
def cli(foo: float, bar: int):
    """Help text for CLI"""
    pass


@cli.group("subgroup")
def subgroup():
    """Help text for subgroup"""


@cli.group("subcommand")
def subcommand():
    """Help text for subcommand"""


cli()

And I run it and, well...

Hmm. That doesn't seem right! I CTRL+F the code for bold cyan and find this:

And then I get digging and start seeing a few more issues:

• STYLE_USAGE_COMMAND only works as a global, not via the rich_config, and is only ever covered by code in cli.main(). This seems like it should not be the case.
• The print usage thing is not stylized at all.
• "Try [blue]'{command} {option}'[/] for help." also does not really allow for any formatting.

I think these should be possible to remedy before 1.7.0 release, so I will look into it. I will be honest, I have not paid too much close attention to the "rich" side of this code until now (been mostly focusing on the "click" side, plus drudgery like testing/linting etc.). So now is my time to dig a little deeper.

What I want to fix

• I want to make sure you can style the command in Usage: [command] ... (currently no style, but seems to want to use config.style_command or perhaps something new like config.style_base_command, or maybe coalesce if one or the other is None).
• I want to make sure you can style the list of subcommands (currently bold cyan is hardcoded, but seems to want to use either config.style_command or something new, such as config.style_command)
• I want to make sure the Try ... for help is stylized rather than always being blue. (I think this one is straightforward.)

For now I will refrain from introducing new style options and just rely on config.style_command for both the "base" command, as well as the subcommand list and the Try [command] for help thing.

This makes things a lot easier for us to not have to deal with commands and subcommands separately. Note two things:

1. I cannot see any situation where style_command is really being used in the code. It is only ever passed in rich.theme.Theme. But, It is not used in any highlighters!

2. Try [command] can also include both arguments and subcommands, but we will just be coloring it all using style_command:

 Usage: docs.py FOO subgroup [OPTIONS] COMMAND [ARGS]...                                                                                                                     
                                                                                                                                                                             
 Try 'docs.py FOO subgroup --help' for help.                                                                                                                                 
╭─ Error ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ No such option: --heldfp Did you mean --help?                                                                                                                             │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
                                              

Is my solution to add config.style_command to format the list of subcommands as well as the "Usage: [command]" fine? cc @ewels.

---

[Daniel Reeves]

OK, slight update after doing a little research...

• It looks like STYLE_COMMAND is new code. I was worried it would break something for users, but actually, it will not. The release of 1.6.1 does not include any styling for this. See this file for where it was added: 958b45a
  • It is possible that at some point it was then moved to a highlighter and then at another point the highlighter was then removed. Not going to go too deep into the tank to figure this out. But long story short, it truly does not do anything right now.
  • It has never referred to the Usage: ... thing. I do not see anywhere in the code any situations where the base command or "command path" has ever been stylized.
• What I am thinking about how to proceed:
  • I can get on board with the API decision to have it refer to the list of subcommands/subgroups.
  • I see that STYLE_USAGE_COMMAND is supposed to refer to the "command path" that follows after the "Usage: ..." stuff. I can see that because, when I mess around with it then run rich-click --help, I see that this is what changes. So that should also be true for CLIs build in rich-click, rather than just the rich-click CLI itself.

So I will just go ahead and make those two changes in a new PR.