gen-crd-api-reference-docs

README

Kubernetes Custom Resource API Reference Docs generator

If you have a project that is Custom Resource Definitions and wanted to generate API Reference Docs like this this tool is for you.

Current Users

• Knative API reference docs
• Kubeflow API reference docs
• Agones API reference docs
• [[ADD YOUR PROJECT HERE]]

Why

Normally you would want to use the same docs generator as Kubernetes API reference, but here's why I wrote a different parser/generator:

1. Today, Kubernetes API does not provide OpenAPI specs for CRDs (e.g. Knative), therefore the gen-apidocs generator used by Kubernetes won't work.

2. Even when Kubernetes API starts providing OpenAPI specs for CRDs, your CRD must have a validation schema (e.g. Knative API doesn't!)

3. Kubernetes gen-apidocs parser relies on running a kube-apiserver and calling /apis endpoint to get OpenAPI specs to generate docs. This tool doesn't need that!

How

This is a custom API reference docs generator that uses the k8s.io/gengo project to parse types and generate API documentation from it.

Capabilities of this tool include:

• Doesn't depend on OpenAPI specs, or kube-apiserver, or a running cluster.
• Relies only on the Go source code (pkg/apis/**/*.go) to parse API types.
• Can link to other sites for external APIs. For example, if your types have a reference to Kubernetes core/v1.PodSpec, you can link to it.
• Configurable settings to hide certain fields or types entirely from the generated output.
• Either output to a file or start a live http-server (for rapid iteration).
• Supports markdown rendering from godoc type, package and field comments.

Try it out

1. Clone this repository.

2. Make sure you have go1.11+ instaled. Then run go build, you should get a refdocs binary executable.

3. Clone a Knative repository, set GOPATH correctly, and call the compiled binary within that directory.

   # go into a repository root with GOPATH set. (I use my own script
   # goclone(1) to have a separate GOPATH for each repo I clone.)
   $ goclone knative/build
   
   $ /path/to/refdocs \
       -config "/path/to/example-config.json" \
       -api-dir "github.com/knative/build/pkg/apis/build/v1alpha1" \
       -out-file docs.html
   

4. Visit docs.html to view the results.

---

This is not an official Google project. See LICENSE.