The custom resource documentation is generated using the same toolchain as Kubernetes, but wrapped up in a series of codegen commands so that you don’t have to download and setup the different tools yourself.
The HTML docs are generated via an OpenAPI specification which in turn is generated from Go Structs which are generated from the code comments.
To generate the structs and the OpenAPI specification run:
$ make generate-openapi
and to generate the HTML run:
You should run make generate-openapi whenever you change the custom resources, and check the generated changes into
source control. This means that there is always a tagged version of the OpenAPI spec available for others to use.
make generate-docs is run by the release build, and the changes are automatically uploaded to the Jenkins X
website on every release. They’ll be available a few minutes after the release build completes.
Making changes to the documentation
Each file for which you want to generate docs must be located in the jenkins.io/v1 directory, and must have a the
comment at the top of the file.
To exclude a type or member, add
Comments on types are ignored. Comments on struct fields are used as the description for each field.
The left hand menu is generated from the resource_categories in config.yaml. The introductory text for each category is authored as
OpenAPI spec can have extensions on types. To define one or more extensions on a type or its member
add +k8s:openapi-gen=x-kubernetes-$NAME:$VALUE to the comment lines before type/member. A type/member can
have multiple extensions. The rest of the line in the comment will be used as $VALUE so there is no need to
escape or quote the value string. Extensions can be used to pass more information to client generators or
documentation generators. For example a type might have a friendly name to be displayed in documentation or
being used in a client’s fluent interface.
Custom OpenAPI type definitions
Custom types which otherwise don’t map directly to OpenAPI can override their
OpenAPI definition by implementing a function named “OpenAPIDefinition” with
the following signature: