k8s-api-docgen
is a tool that reads Go source files to extract metadata
about Kubernetes API custom resources defined by the developer in Godoc
and to produce different kinds of output - such as JSON or Markdown.
Its main use case is to automatically generate documentation in Markdown format to be used within a CI/CD pipeline of a software written in Go for Kubernetes, such as an operator.
To compile this software you need:
-
a working Go compiler;
-
a
make
installation (the one in MacOSX and the GNU ones are known to be working correctly).
The code has been tested on MacOS X and Linux, but should resonably work in other platforms too.
Just use the Makefile:
$ make
[...]
The tool needs to have access to the Go source files for your Kubernetes API. These are the files that will also be used by controller-gen to generate the CRD.
Supposing these files are reachable at ../operator/api/v1
you can extract the
documentation in JSON format via:
$ ./bin/k8s-api-docgen ../operator/api/v1/*types.go
The JSON stream will be written to standard output. Should you desire to
create a file, you can use the -o
option as follows:
$ ./bin/k8s-api-docgen -o documentation.json ../operator/api/v1/*types.go
Using the -t
option with md
value, you can also extract the documentation in Markdown format via:
$ ./bin/k8s-api-docgen -t md -o documentation.md ../operator/api/v1/*types.go
If you provide a -c
option, you could specify your custom configuration file in YAML format via
$ ./bin/k8s-api-docgen -t md -c md-configuration.yaml -o documentation.md ../operator/api/v1/*types.go
This option is useful for linking K8s documentation to types and customizing table headers.
k8s-api-docgen
is distributed under Apache License 2.0.
Copyright (C) 2021 EnterpriseDB Corporation.
Some portions Copyright 2016 The prometheus-operator Authors.