WIP: Help (--help) page customization high level design

[Rowlando13]

This is a work in progress...

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 and infinite space for customization with a large number of edge case. The edge cases stem from the historical development of terminals, the very many shells and terminal emulators, each running on one or more of the major 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. Basically writes the lowest primitive(bytes?) directly to the terminal with access to the full context. The intention is for terminal customization libraries like Rich to be able to directly sent their primitives to the terminal while having access to as much information about the current invocation as possible.

Advantages

• the potentially infinite space for customization is clearly bound ed 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 full 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.