Design more human-friendly type presentation

[medubelko]

Background

The type documentation takes the perspective of a Python developer. Collections are represented as Pythonic lists, custom types are revealed, and the formatting prefers one-liners.

Type
Any of: ['stable', 'devel']

In YAML references, which are a major consumer of Kitbash, these aren't very friendly. Users who configure software through YAML as a rule shouldn't need an understanding of the underlying code's typing, only YAML's own types. YAML deliberately abstracts anything beyond primitive types, and even muddles the distinction between different collections.

It would be ideal if users who produce YAML references could keep the types as simple as possible.

It would also be preferable if the type presentation itself were simply better across-the-board.

Request

1. Design better formatting and conventions for type presentation

Don't delimit multiple items with pseudocode signatures like [a,b,c], type[].

Delineate between values and documentation verbiage. Only items that users could actually insert should be shown as code.

Using whitespaces and newlines appropriately.

Using plain-English words for types. Users shouldn't need to be able to recognise Python type naming like str to understand YAML inputs.

Here's a possible approach, using an enum for example:

Type
String. Valid values are:
"a"
"b"
"c"

2. Make non-primitive types an option in the two directives

The option name could be something like :show-all-types:.

3. Disable non-primitive types by default

The writer ought to be conscious and deliberate in their inclusion of deeper types.