README
¶
Kubernetes API documentation generator
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.
Requirements
To compile this software you need:
-
a working Go compiler;
-
a
makeinstallation (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.
How to compile the code
Just use the Makefile:
$ make
[...]
Usage instructions
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.
Copyright
k8s-api-docgen is distributed under Apache License 2.0.
Copyright (C) 2021 EnterpriseDB Corporation.
Some portions Copyright 2016 The prometheus-operator Authors.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
internal
|
|
|
docgen
Package docgen contain the main functions to preprocess an AST and to write the documentation to the output file
|
Package docgen contain the main functions to preprocess an AST and to write the documentation to the output file |
|
log
Package log handles logging
|
Package log handles logging |
|
pkg
|
|
|
parser
Package parser contain the parsing code
|
Package parser contain the parsing code |
|
renderer/json
Package json contain the code exporting the internal data to JSON
|
Package json contain the code exporting the internal data to JSON |
|
renderer/md
Package md contain the code exporting the internal data to markdown
|
Package md contain the code exporting the internal data to markdown |