chore: Add code docs extractor

[nieomylnieja]

Motivation

In order to better manage and unify our objects' documentation we need a mechanism to export the documentation in a flexible format which can than be used to either generate online docs or help other tools present more details to the user.

Summary

Added docgen tool which extracts Go docs and merges them with validation plan as well as applies additional formatting and custom logic on top of these two sources.

The output format is a structured YAML file which can be digested by any other tool to further format the docs.

Along the way I've also noticed some gaps and improved a couple of things.
This PR DOES NOT attempt to finish the documentation process.

Additional changes:

• added missing apiVersion and kind fields validation
• improved validation plan generation
• added tests for objects' examples
• improved selected docs

Example for Project

- kind: Project
  version: n9/v1alpha
  properties:
  - path: $
    type: Project
    package: github.com/nobl9/nobl9-go/manifest/v1alpha/project
    doc: |-
      Project is the primary grouping of resources in Nobl9.
      Most objects are scoped to a certain Project.
      For more details, see [projects in the Nobl9 platform].
      
      [projects in the Nobl9 platform]: https://docs.nobl9.com/getting-started/rbac/#projects-in-the-nobl9-platform
    childrenPaths:
    - $.apiVersion
    - $.kind
    - $.metadata
    - $.spec
    - $.organization
    - $.manifestSrc
  - path: $.apiVersion
    type: string
    doc: Version represents the specific version of the manifest.
    rules:
    - description: should be equal to 'n9/v1alpha'
      errorCode: equal_to
  - path: $.kind
    type: string
    doc: Kind represents all the object kinds available in the API to perform operations on.
    rules:
    - description: should be equal to 'Project'
      errorCode: equal_to
  - path: $.metadata
    type: Metadata
    package: github.com/nobl9/nobl9-go/manifest/v1alpha/project
    doc: Metadata provides identity information for Project.
    childrenPaths:
    - $.metadata.name
    - $.metadata.displayName
    - $.metadata.labels
    - $.metadata.annotations
  - path: $.metadata.name
    type: string
    fieldDoc: Name is used to uniquely identify the Project.
    rules:
    - description: length must be between 1 and 63
      errorCode: string_length
    - description: "string must match regular expression: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$' (e.g. 'my-name', '123-abc')"
      details: a DNS-1123 compliant name must consist of lower case alphanumeric characters or '-', and must start and end with an alphanumeric character
      errorCode: string_match_regexp
  - path: $.metadata.displayName
    type: string
    fieldDoc: DisplayName allows defining a more human-readable name for the Project.
    isOptional: true
    rules:
    - description: length must be between 0 and 63
      errorCode: string_length
  - path: $.metadata.labels
    type: map[string][]string
    doc: |-
      Labels are key-value pairs that can be attached to SLOs, services, projects, and alert policies.
      Labels are used to select and filter Nobl9 objects.
    examples:
    - |-
      team:
        - green
        - sales
      env:
        - prod
        - dev
      region:
        - us
        - eu
      area:
        - latency
        - slow-check
    rules:
    - description: TODO
    childrenPaths:
    - $.metadata.labels.~
    - $.metadata.labels.*
    - $.metadata.labels.*[*]
  - path: $.metadata.labels.~
    type: string
    rules:
    - description: length must be between 1 and 63
      errorCode: string_length
    - description: "string must match regular expression: '^\\p{Ll}([_\\-0-9\\p{Ll}]*[0-9\\p{Ll}])?$'"
      errorCode: string_match_regexp
  - path: $.metadata.labels.*
    type: "[]string"
    rules:
    - description: elements must be unique
      errorCode: slice_unique
  - path: $.metadata.labels.*[*]
    type: string
    rules:
    - description: length must be less than or equal to 200
      errorCode: string_max_length
  - path: $.metadata.annotations
    type: map[string]string
    doc: |-
      MetadataAnnotations are non-identifiable key-value pairs that can be attached to
      SLOs, services, projects, and alert policies.
      Metadata annotations are used for descriptive purposes only.
    examples:
    - |-
      team: sales
      env: prod
      region: us
      area: latency
    rules:
    - description: TODO
    childrenPaths:
    - $.metadata.annotations.~
    - $.metadata.annotations.*
  - path: $.metadata.annotations.~
    type: string
    rules:
    - description: length must be between 1 and 63
      errorCode: string_length
    - description: "string must match regular expression: '^\\p{Ll}([_\\-0-9\\p{Ll}]*[0-9\\p{Ll}])?$'"
      errorCode: string_match_regexp
  - path: $.metadata.annotations.*
    type: string
    rules:
    - description: length must be less than or equal to 1050
      errorCode: string_max_length
  - path: $.spec
    type: Spec
    package: github.com/nobl9/nobl9-go/manifest/v1alpha/project
    doc: Spec holds detailed specification of the Project.
    childrenPaths:
    - $.spec.description
  - path: $.spec.description
    type: string
    fieldDoc: Description allows for a more detailed description of the Project.
    rules:
    - description: length must be between 0 and 1050
      errorCode: string_description
  - path: $.manifestSrc
    type: string
  examples:
  - |
    apiVersion: n9/v1alpha
    kind: Project
    metadata:
      name: my-project
      displayName: My Project
      labels:
        team: [ green, orange ]
        region: [ eu-central-1 ]
    spec:
      description: Example Project

[daniel-zelazny]

it was my first exp with that tool, nice! 🥇