gen-crd-api-reference-docs

command module
v0.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 5, 2023 License: Apache-2.0 Imports: 25 Imported by: 0

README

Kubernetes Custom Resource API Reference Docs generator

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

Current Users

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+ installed. Then run go build, you should get a gen-crd-api-reference-docs binary executable in the current directory.

  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/gen-crd-api-reference-docs \
        -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.

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
Placeholder file to make Go vendor this directory properly.
Placeholder file to make Go vendor this directory properly.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL