Nail/fission-src
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add support for generating CRD docs (#2273)

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

Signed-off-by: Sanket Sudake <sanketsudake@gmail.com>
This commit is contained in:
Sanket Sudake
2021-11-30 15:54:53 +05:30
committed by GitHub
parent 24737e8958
commit fe0c1e3683
11 changed files with 48 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Makefile
+7
View File
@@ -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
+1 -1
View File
@@ -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
+2 -2
View File
@@ -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
+3 -3
View File
@@ -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
+2 -2
View File
@@ -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
+1 -1
View File
@@ -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
-4
View File
@@ -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
+10 -10
View File
@@ -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
// it's supported by most of environments except tensorflow-serving.
// Version "1" allows user to run code snippet in a file, and
// 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
+8 -23
View File
@@ -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
+7
View File
@@ -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
+7
View File
@@ -0,0 +1,7 @@
---
title: "Fission CRD Reference"
weight: 99
description: >
Fission Custom Resources Definition(CRD) Reference
url: /docs/crd-reference/
---