https://github.com/enterprisedb/k8s-api-docgen
Reads Go source files to extract metadata about Kubernetes API custom resources defined by the developer in Godoc and produces different kinds of output - such as JSON or Markdown.
https://github.com/enterprisedb/k8s-api-docgen
developer documentation godoc golang
Last synced: 12 months ago
JSON representation
Reads Go source files to extract metadata about Kubernetes API custom resources defined by the developer in Godoc and produces different kinds of output - such as JSON or Markdown.
- Host: GitHub
- URL: https://github.com/enterprisedb/k8s-api-docgen
- Owner: EnterpriseDB
- License: apache-2.0
- Created: 2021-03-10T12:45:29.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2023-06-14T16:09:52.000Z (about 3 years ago)
- Last Synced: 2025-06-06T14:08:03.008Z (about 1 year ago)
- Topics: developer, documentation, godoc, golang
- Language: Go
- Homepage:
- Size: 40 KB
- Stars: 6
- Watchers: 17
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE-OF-CONDUCT.md
Awesome Lists containing this project
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](https://blog.golang.org/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](https://golang.org/);
- 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.
## 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](https://book.kubebuilder.io/reference/controller-gen.html) 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.