Help (--help) page customization high level design

[Rowlando13]

Intro

This is a possible high level design for help page(passing in --help) customization. I hope to come to an ideal design that supports the standard and advanced user. I will put together my thoughts then try to work with the community to improve it.

Design

Help pages are basically an infinite space for customization with a large number of edge cases. The edge cases stem from the historical development of terminals and the very many shells and terminal emulators, each running on one or more operating systems. Because of this, I think Click should have 2 ways to generate help:

1. Help pages generated directly by Click. No formatting except line breaks and alignment. The focus is on displaying information. Basically the current help pages with a couple of more features. There is a lot of customization on the text displayed but no layout or otherwise formatting customization.

2. Very low level and completely customizable. The intention is for terminal customization libraries like Rich to be able to directly send their primitives to the terminal while having access to as much information about the current invocation as possible. The hope is that some people will write nice plugins, and then most users can pick a plugin that caters to their sense of taste.

Advantages

• the potentially infinite space for customization is clearly bounded for the maintainers in a way that is easily communicated to users

• the bounding frees Click maintainers to concern themselves with making a good CLI toolkit

• The design also allows for explicit hooks for very dynamic help page customization.

Possible implementation path:

• implement low level API
• implement the standard help page on top of low level API

Downsides:

• the default help page is a bit lackluster

[davidism]

Could you be more specific about what you're referring to? Is this about the help output that's shown with --help? Or something else?

[Rowlando13]

Yeah.