cue: support runnable examples as part of package documentation

[mvdan]

Go has support for examples (https://pkg.go.dev/testing#hdr-Examples) as part of package docs, and they can be runnable or testable as well, meaning that running the code gives some output - and this output is shown with the docs, and verified to be true when one runs go test.

For instance, see one rendered runnable example of ours here: https://pkg.go.dev/cuelang.org/[email protected]/cue#example-Context

Examples are really useful in documentation, and examples which can be run and verified are even more useful - as they don't go stale, and the user can immediately take the code and try it out. We should support them in CUE too.

One rough idea is to copy or reuse some of the playground's design (https://cuelang.org/play) given that its inputs are:

• which function to be run (export, def, validate, etc)
• which input files, and in what format

So, here's a strawman for what an example could look like:

-- schema.cue --
package p

#Person: {
    name!: string
    age!: int & >= 0 & <120
}
-- example.cue --
package p

#Person: {
    name!: string
    age!: int & >= 0 & <120
}

// A valid person conforms to the schema.
_examples: validate: success: validPerson: {
    schema:  #Person
    data:    {name: "John", age: 29}
}

_examples: validate: fail: missingPersonAge: {
    schema: #Person
    data:   {name: "John"}
    error: "age: field is required but not present"
}

For runnable examples in package docs for the central registry, it's probably necessary to support dependency resolution too, so that we can e.g. have runnable examples with k8s schemas from packages which themselves have dependencies on other packages or modules, following their cue.mod.