canonical / canonical/pydantic-kitbash

Design more human-friendly type presentation

Open
#40 0 comments 0 reactions 1 assignee Claimed by @jahn-junior View on GitHub
Dominant language
Python
Stars
3
Forks
2
Avg merge
1d 5h
Merged PRs (30d)
9

Description

## 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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.