crd-docs-generator

crd-docs-generator

Generates schema reference documentation for Kubernetes Custom Resource Definitions (CRDs).

This tool is built to generate our Management API CRD schema reference.

The generated output consists of Markdown files packed with HTML. By itself, this does not provide a fully readable and user-friendly set of documentation pages. Instead it relies on the HUGO website context, as the giantswarm/docs repository, to provide an index page and useful styling.

Assumptions/Prerequisites

This tool relies on:

• CRDs being defined in the giantswarm/apiextensions repository
  • ... as one YAML file per CRD in the apiextensions config/crd folder folder
  • ... or in the apiextensions helm folder (deeper in the structure) as a file named upstream.yaml.
• CRDs providing an OpenAPIv3 validation schema
  • either in the .spec.validation section of a CRD containg only one version
  • or in the .spec.versions[*].schema position of a CRD containing multiple versions
• OpenAPIv3 schemas containing description attributes for every property.
• The topmost description value explaining the CRD itself. (For a CRD containing multiple versions, the first description found is used as such.)
• CR examples to be found in the apiextensions docs/cr folder as one example per YAML file.

Usage

The generator can be executed in Docker using a command like this:

docker run \
    -v $PWD/path/to/output-folder:/opt/crd-docs-generator/output \
    -v $PWD:/opt/crd-docs-generator/config \
    quay.io/giantswarm/crd-docs-generator \
      --commit-reference v1.2.3 \
      --config /opt/crd-docs-generator/config/config.yaml \
      --template /opt/crd-docs-generator/config/crd.template

or in Go like this:

go run main.go \
  --config service/config/testdata/config1.yaml \
  --commit-reference v1.2.3 \
  --template ./crd.template

The volume mapping defines where the generated output will land.

TODO

• Parse template only once instead of for every CRD