Add support for generating CRD docs (#2273)

* Add support for generating CRD docs
* Correct typos in custom resource definitions

Signed-off-by: Sanket Sudake <sanketsudake@gmail.com>

Makefile

@@ -82,6 +82,13 @@ generate-swagger-doc:
 generate-cli-docs:
 	go run tools/cmd-docs/main.go -o "../fission.io/content/en/docs/fission-cli"
 
+generate-crd-ref-docs:
+	# crd-ref-docs: https://github.com/elastic/crd-ref-docs
+	crd-ref-docs --source-path=pkg/apis/core/v1 --config=tools/crd-ref-docs/config.yaml --renderer markdown
+	cp tools/crd-ref-docs/header.md crd_docs.md
+	cat out.md >> crd_docs.md && rm out.md
+	cp crd_docs.md ../fission.io/content/en/docs/crd/_index.md
+
 all-generators: codegen generate-crds generate-swagger-doc
 
 skaffold-prebuild:

crds/v1/fission.io_environments.yaml

@@ -9399,7 +9399,7 @@ spec:
                 format: int64
                 type: integer
               version:
-                description: "Version is the Environment API version \n Version \"1\" allows user to run code snippet in a file and it's supported by most of environments except tensorflow-serving. \n Version \"2\" supports downloading and compiling user function if source archive is not empty. \n Version \"3\" is almost the same with v2, but you're able to control the size of pre-warm pool of the environment."
+                description: "Version is the Environment API version \n Version \"1\" allows user to run code snippet in a file, and it's supported by most of the environments except tensorflow-serving. \n Version \"2\" supports downloading and compiling user function if source archive is not empty. \n Version \"3\" is almost the same with v2, but you're able to control the size of pre-warm pool of the environment."
                 type: integer
             required:
             - runtime

crds/v1/fission.io_functions.yaml

@@ -41,7 +41,7 @@ spec:
                     description: ExecutionStrategy specifies low-level parameters for function execution, such as the number of instances.
                     properties:
                       ExecutorType:
-                        description: "ExecutorType is the executor type of a function used. Defaults to \"poolmgr\". \n Available value:  - poolmgr  - newdeploy  - container"
+                        description: "ExecutorType is the executor type of function used. Defaults to \"poolmgr\". \n Available value:  - poolmgr  - newdeploy  - container"
                         type: string
                       MaxScale:
                         description: This is only for newdeploy to set up maximum replicas of deployment.
@@ -57,7 +57,7 @@ spec:
                         type: integer
                     type: object
                   StrategyType:
-                    description: StrategyType is the strategy type of a function. Now it only supports 'execution'.
+                    description: StrategyType is the strategy type of function. Now it only supports 'execution'.
                     type: string
                 type: object
               concurrency:

crds/v1/fission.io_httptriggers.yaml

@@ -33,7 +33,7 @@ spec:
             description: HTTPTriggerSpec is for router to expose user functions at the given URL path.
             properties:
               createingress:
-                description: If CreateIngress is true, router will create a ingress definition.
+                description: If CreateIngress is true, router will create an ingress definition.
                 type: boolean
               functionref:
                 description: FunctionReference is a reference to the target function.
@@ -58,12 +58,12 @@ spec:
                 description: 'TODO: remove this field since we have IngressConfig already Deprecated: the original idea of this field is not for setting Ingress. Since we have IngressConfig now, remove Host after couple releases.'
                 type: string
               ingressconfig:
-                description: 'TODO: make IngressConfig a independent Fission resource IngressConfig for router to set up Ingress.'
+                description: 'TODO: make IngressConfig an independent Fission resource IngressConfig for router to set up Ingress.'
                 properties:
                   annotations:
                     additionalProperties:
                       type: string
-                    description: Annotations will be add to metadata when creating Ingress.
+                    description: Annotations will be added to metadata when creating Ingress.
                     nullable: true
                     type: object
                   host:

crds/v1/fission.io_packages.yaml

@@ -50,7 +50,7 @@ spec:
                         type: string
                     type: object
                   literal:
-                    description: Literal contents of the package. Can be used for encoding packages below TODO (256KB?) size.
+                    description: Literal contents of the package. Can be used for encoding packages below TODO (256 KB?) size.
                     format: byte
                     type: string
                   type:
@@ -84,7 +84,7 @@ spec:
                         type: string
                     type: object
                   literal:
-                    description: Literal contents of the package. Can be used for encoding packages below TODO (256KB?) size.
+                    description: Literal contents of the package. Can be used for encoding packages below TODO (256 KB?) size.
                     format: byte
                     type: string
                   type:

hack/update-swagger-docs.sh

@@ -18,7 +18,7 @@ kube::swagger::gen_types_swagger_doc() {
 
   echo "Generating swagger type docs for ${group_version} at ${gv_dir}"
 
-  sed 's/YEAR/2017/' hack/boilerplate.txt > "$TMPFILE"
+  # sed 's/YEAR/2017/' hack/boilerplate.txt > "$TMPFILE"
   echo "package ${group_version##*/}" >> "$TMPFILE"
   cat >> "$TMPFILE" <<EOF
 // This file contains a collection of methods that can be used from go-restful to

pkg/apis/core/v1/doc.go

@@ -22,10 +22,6 @@ limitations under the License.
 // +groupName=fission.io
 // +groupGoName=core
 //
-// In order not to break the backward compatibility, keep coreV1 types stay
-// at "fission.io" group instead of moving them to "core.fission.io".
-// If the value of group is different from the one we register, the
-// CRD client will not be able to get anything from the API server.
 package v1
 
 const (

pkg/apis/core/v1/types.go

@@ -229,7 +229,7 @@ type (
 	// externally.
 	ArchiveType string
 
-	// Archive contains or references a collection of source or
+	// Archive contains or references a collection of sources or
 	// binary files.
 	Archive struct {
 		// Type defines how the package is specified: literal or URL.
@@ -240,7 +240,7 @@ type (
 		Type ArchiveType `json:"type,omitempty"`
 
 		// Literal contents of the package. Can be used for
-		// encoding packages below TODO (256KB?) size.
+		// encoding packages below TODO (256 KB?) size.
 		// +optional
 		Literal []byte `json:"literal,omitempty"`
 
@@ -254,7 +254,7 @@ type (
 		Checksum Checksum `json:"checksum,omitempty"`
 	}
 
-	// EnvironmentReference is a reference to a environment.
+	// EnvironmentReference is a reference to an environment.
 	EnvironmentReference struct {
 		Namespace string `json:"namespace"`
 		Name      string `json:"name"`
@@ -431,7 +431,7 @@ type (
 		// +optional
 		ExecutionStrategy ExecutionStrategy `json:"ExecutionStrategy"`
 
-		// StrategyType is the strategy type of a function.
+		// StrategyType is the strategy type of function.
 		// Now it only supports 'execution'.
 		// +optional
 		StrategyType StrategyType `json:"StrategyType"`
@@ -450,7 +450,7 @@ type (
 	// and resources allocated to the function pod.
 	ExecutionStrategy struct {
 
-		// ExecutorType is the executor type of a function used. Defaults to "poolmgr".
+		// ExecutorType is the executor type of function used. Defaults to "poolmgr".
 		//
 		// Available value:
 		//  - poolmgr
@@ -578,8 +578,8 @@ type (
 	EnvironmentSpec struct {
 		// Version is the Environment API version
 		//
-		// Version "1" allows user to run code snippet in a file and
+		// Version "1" allows user to run code snippet in a file, and
-		// it's supported by most of environments except tensorflow-serving.
+		// it's supported by most of the environments except tensorflow-serving.
 		//
 		// Version "2" supports downloading and compiling user function if source archive is not empty.
 		//
@@ -681,11 +681,11 @@ type (
 		// FunctionReference is a reference to the target function.
 		FunctionReference FunctionReference `json:"functionref"`
 
-		// If CreateIngress is true, router will create a ingress definition.
+		// If CreateIngress is true, router will create an ingress definition.
 		// +optional
 		CreateIngress bool `json:"createingress"`
 
-		// TODO: make IngressConfig a independent Fission resource
+		// TODO: make IngressConfig an independent Fission resource
 		// IngressConfig for router to set up Ingress.
 		// +optional
 		IngressConfig IngressConfig `json:"ingressconfig"`
@@ -693,7 +693,7 @@ type (
 
 	// IngressConfig is for router to set up Ingress.
 	IngressConfig struct {
-		// Annotations will be add to metadata when creating Ingress.
+		// Annotations will be added to metadata when creating Ingress.
 		// +optional
 		// +nullable
 		Annotations map[string]string `json:"annotations"`

pkg/apis/core/v1/zz_generated.swagger_doc_generated.go

@@ -1,18 +1,3 @@
-/*
-Copyright The Fission Authors.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-*/
 package v1
 
 // This file contains a collection of methods that can be used from go-restful to
@@ -26,9 +11,9 @@ package v1
 // Those methods can be generated by using hack/update-swagger-docs.sh
 // AUTO-GENERATED FUNCTIONS START HERE
 var map_Archive = map[string]string{
-	"":         "Archive contains or references a collection of source or binary files.",
+	"":         "Archive contains or references a collection of sources or binary files.",
 	"type":     "Type defines how the package is specified: literal or URL. Available value:\n - literal\n - url",
-	"literal":  "Literal contents of the package. Can be used for encoding packages below TODO (256KB?) size.",
+	"literal":  "Literal contents of the package. Can be used for encoding packages below TODO (256 KB?) size.",
 	"url":      "URL references a package.",
 	"checksum": "Checksum ensures the integrity of packages referenced by URL. Ignored for literals.",
 }
@@ -120,7 +105,7 @@ func (EnvironmentList) SwaggerDoc() map[string]string {
 }
 
 var map_EnvironmentReference = map[string]string{
-	"": "EnvironmentReference is a reference to a environment.",
+	"": "EnvironmentReference is a reference to an environment.",
 }
 
 func (EnvironmentReference) SwaggerDoc() map[string]string {
@@ -129,7 +114,7 @@ func (EnvironmentReference) SwaggerDoc() map[string]string {
 
 var map_EnvironmentSpec = map[string]string{
 	"":                             "EnvironmentSpec contains with builder, runtime and some other related environment settings.",
-	"version":                      "Version is the Environment API version\n\nVersion \"1\" allows user to run code snippet in a file and it's supported by most of environments except tensorflow-serving.\n\nVersion \"2\" supports downloading and compiling user function if source archive is not empty.\n\nVersion \"3\" is almost the same with v2, but you're able to control the size of pre-warm pool of the environment.",
+	"version":                      "Version is the Environment API version\n\nVersion \"1\" allows user to run code snippet in a file, and it's supported by most of the environments except tensorflow-serving.\n\nVersion \"2\" supports downloading and compiling user function if source archive is not empty.\n\nVersion \"3\" is almost the same with v2, but you're able to control the size of pre-warm pool of the environment.",
 	"runtime":                      "Runtime is configuration for running function, like container image etc.",
 	"builder":                      "(Optional) Builder is configuration for builder manager to launch environment builder to build source code into deployable binary.",
 	"allowedFunctionsPerContainer": "(Optional) defaults to 'single'. Fission workflow uses 'infinite' to load multiple functions in one function pod. Available value: - single - infinite",
@@ -147,7 +132,7 @@ func (EnvironmentSpec) SwaggerDoc() map[string]string {
 
 var map_ExecutionStrategy = map[string]string{
 	"":                      "ExecutionStrategy specifies low-level parameters for function execution, such as the number of instances.\n\nMinScale affects the cold start behavior for a function. If MinScale is 0 then the deployment is created on first invocation of function and is good for requests of asynchronous nature. If MinScale is greater than 0 then MinScale number of pods are created at the time of creation of function. This ensures faster response during first invocation at the cost of consuming resources.\n\nMaxScale is the maximum number of pods that function will scale to based on TargetCPUPercent and resources allocated to the function pod.",
-	"ExecutorType":          "ExecutorType is the executor type of a function used. Defaults to \"poolmgr\".\n\nAvailable value:\n - poolmgr\n - newdeploy\n - container",
+	"ExecutorType":          "ExecutorType is the executor type of function used. Defaults to \"poolmgr\".\n\nAvailable value:\n - poolmgr\n - newdeploy\n - container",
 	"MinScale":              "This is only for newdeploy to set up minimum replicas of deployment.",
 	"MaxScale":              "This is only for newdeploy to set up maximum replicas of deployment.",
 	"TargetCPUPercent":      "This is only for newdeploy to set up target CPU utilization of HPA.",
@@ -240,7 +225,7 @@ var map_HTTPTriggerSpec = map[string]string{
 	"method":        "Use Methods instead of Method. This field is going to be deprecated in a future release HTTP method to access a function.",
 	"methods":       "HTTP methods to access a function",
 	"functionref":   "FunctionReference is a reference to the target function.",
-	"createingress": "If CreateIngress is true, router will create a ingress definition.",
+	"createingress": "If CreateIngress is true, router will create an ingress definition.",
 	"ingressconfig": "IngressConfig for router to set up Ingress.",
 }
 
@@ -250,7 +235,7 @@ func (HTTPTriggerSpec) SwaggerDoc() map[string]string {
 
 var map_IngressConfig = map[string]string{
 	"":            "IngressConfig is for router to set up Ingress.",
-	"annotations": "Annotations will be add to metadata when creating Ingress.",
+	"annotations": "Annotations will be added to metadata when creating Ingress.",
 	"path":        "Path is for path matching. The format of path depends on what ingress controller you used.",
 	"host":        "Host is for ingress controller to apply rules. If host is empty or \"*\", the rule applies to all inbound HTTP traffic.",
 	"tls":         "TLS is for user to specify a Secret that contains TLS key and certificate. The domain name in the key and crt must match the value of Host field.",
@@ -263,7 +248,7 @@ func (IngressConfig) SwaggerDoc() map[string]string {
 var map_InvokeStrategy = map[string]string{
 	"":                  "InvokeStrategy is a set of controls over how the function executes. It affects the performance and resource usage of the function.\n\nAn InvokeStrategy is of one of two types: ExecutionStrategy, which controls low-level parameters such as which ExecutorType to use, when to autoscale, minimum and maximum number of running instances, etc. A higher-level AbstractInvokeStrategy will also be supported; this strategy would specify the target request rate of the function, the target latency statistics, and the target cost (in terms of compute resources).",
 	"ExecutionStrategy": "ExecutionStrategy specifies low-level parameters for function execution, such as the number of instances.",
-	"StrategyType":      "StrategyType is the strategy type of a function. Now it only supports 'execution'.",
+	"StrategyType":      "StrategyType is the strategy type of function. Now it only supports 'execution'.",
 }
 
 func (InvokeStrategy) SwaggerDoc() map[string]string {

tools/crd-ref-docs/config.yaml

@@ -0,0 +1,7 @@
+processor:
+  ignoreTypes:
+    - "(CanaryConfig|Environment|Function|HTTPTrigger|KubernetesWatchTrigger|MessageQueueTrigger|Package|TimeTrigger)List$"
+  ignoreGroupVersions:
+render:
+  # Version of Kubernetes to use when generating links to Kubernetes API documentation.
+  kubernetesVersion: 1.22

tools/crd-ref-docs/header.md

@@ -0,0 +1,7 @@
+---
+title: "Fission CRD Reference"
+weight: 99
+description: >
+  Fission Custom Resources Definition(CRD) Reference
+url: /docs/crd-reference/
+---