[Feature] `chainsaw explain` command

[chipzoller]

Problem Statement

Chainsaw is growing more complex and capable with more resources as well as more complexity to each resource. It's becoming more difficult to remember the structure of each field especially as more are being added in this early phase of growth. Flipping over to either other examples or the website isn't a great experience as these things can be incomplete and involve switching between workspaces.

Solution Description

Add an explain command just like kubectl explain which allows users to interactively (and recursively) describe and explain API resources.

chainsaw explain test.spec: explain the Test resource under the spec struct. All fields have complete descriptions. chainsaw explain test.spec --recursive: Similar to the above but with a recursive tree structure for all fields underneath.

See an example of this for kubectl:

$ kubectl explain poddisruptionbudget.spec --recursive
GROUP:      policy
KIND:       PodDisruptionBudget
VERSION:    v1

FIELD: spec <PodDisruptionBudgetSpec>

DESCRIPTION:
    Specification of the desired behavior of the PodDisruptionBudget.
    PodDisruptionBudgetSpec is a description of a PodDisruptionBudget.

FIELDS:
  maxUnavailable        <IntOrString>
  minAvailable  <IntOrString>
  selector      <LabelSelector>
    matchExpressions    <[]LabelSelectorRequirement>
      key       <string> -required-
      operator  <string> -required-
      values    <[]string>
    matchLabels <map[string]string>
  unhealthyPodEvictionPolicy    <string>

Alternatives

JSON schemas are ok but they're clunky and, require either adding a CRD to a cluster or adding a line to a file, and are IDE specific.

Additional Context

$ kubectl explain --help
Describe fields and structure of various resources.

 This command describes the fields associated with each supported API resource. Fields are identified via a simple
JSONPath identifier:

        <type>.<fieldName>[.<fieldName>]

 Information about each field is retrieved from the server in OpenAPI format.

Use "kubectl api-resources" for a complete list of supported resources.

Examples:
  # Get the documentation of the resource and its fields
  kubectl explain pods

  # Get all the fields in the resource
  kubectl explain pods --recursive

  # Get the explanation for deployment in supported api versions
  kubectl explain deployments --api-version=apps/v1

  # Get the documentation of a specific field of a resource
  kubectl explain pods.spec.containers

  # Get the documentation of resources in different format
  kubectl explain deployment --output=plaintext-openapiv2

Options:
    --api-version='':
        Use given api-version (group/version) of the resource.

    --output='plaintext':
        Format in which to render the schema. Valid values are: (plaintext, plaintext-openapiv2).

    --recursive=false:
        When true, print the name of all the fields recursively. Otherwise, print the available fields with their
        description.

Usage:
  kubectl explain TYPE [--recursive=FALSE|TRUE] [--api-version=api-version-group]
[--output=plaintext|plaintext-openapiv2] [options]

Use "kubectl options" for a list of global command-line options (applies to all commands).

Slack discussion

No response

Research

• [X] I have searched other issues in this repository and mine is not recorded.

[eddycharly]

adding a line to a file

This sounds like a reasonable effort :)

[chipzoller]

If it's too difficult for you I understand 😉

[eddycharly]

Let's see if someone wants to give it a try 🤞 It's not high priority but would be good to have if we can.