Decorrelate format and printing

[AdrienPensart]

I think something is incompatible in the way rich_format_help is not only formatting the output string
but it's printing it too !

I think this function should just return the formatted string (a rich object is ok) and then let the user choose the Console object himself or another way to print the string.

[ewels]

I'll have a think about this. It's my aim to mimic default click functionality by default, and I'm pretty sure that click prints to the terminal. But it's possible that click has a method to define the output method / return a string etc, in which case I will try to replicate that.

Alternatively I guess we could have a new opt-in config option to return the console object. Needs a bit of thought though, at the moment I think rich-click uses several different console objects for example 🤔

[RhetTbull]

I second this. I have implemented my own help command in click applications that uses Command.get_help to get the formatted help string. get_help calls format_help internally to format the help string but it appears rich_click is printing the formatted help string to the console which means the formatted help string can't be used by custom help functions nor can it be sent to the pager.

[ewels]

Ah ok, if this is different to the standard click functions then I'm more inclined to adjust it.. What is the function in Click that prints to the terminal then?

How would you want to use the formatted help strings from rich-click, out of interest?

[AdrienPensart]

My use case was related to auto-generate a complete README of all commands, and groups subcommands all at once, with this kind of code :

https://github.com/AdrienPensart/click-skeleton/blob/master/click_skeleton/doc.py

[RhetTbull]

What is the function in Click that prints to the terminal then?

I think it's help_option which calls get_help which uses HelpFormatter to do the formatting:

https://github.com/pallets/click/blob/5ba2320454065a78dbb4176e582ab21c990d358c/src/click/decorators.py#L477-L495

My use case is similar to @AdrienPensart and also I've implemented a custom Click Command that overrides get_help to provide custom formatted help for a complex command:

https://github.com/RhetTbull/osxphotos/blob/93de53da5105798fff567c1bf6d032384165380d/osxphotos/cli/help.py#L180-L195

[dwreeves]

I believe that with rich-click 1.8.0, there are tons of ways for both novice and advanced users to get what they want in regards to decoupled text generation and text rendering

pip install rich-click==1.8.0dev2

• you have the rich-click --output=[html,svg] CLI.
• you can pass a Console() yourself into the rich_config() decorator. (Bugged in 1.7, but works in 1.8.)
• subclassing is flexible and composable, and the middle layer of the API is quickly approaching stability

The formatter object still needs a little work, but in fairness to us, it is a little weird because we have to kind of force it to work with the rich Console(). Square peg in round hole. I think other than that we're in a great spot.

I'm going through and cleaning the backlog up, and I'm closing this issue given the sheer amount of abstraction work that's gone on between myself and @BrutalSimplicity. Please re-open an issue if you have any specific concerns still.