diff --git a/.github/workflows/definition-lint.yml b/.github/workflows/definition-lint.yml new file mode 100644 index 000000000..6ba3bd31b --- /dev/null +++ b/.github/workflows/definition-lint.yml @@ -0,0 +1,44 @@ +name: Definition-Lint + +on: + push: + branches: + - master + - release-* + workflow_dispatch: {} + pull_request: + branches: + - master + - release-* + +env: + # Common versions + GO_VERSION: '1.19' + +jobs: + definition-doc: + runs-on: ubuntu-latest + steps: + - name: Setup Go + uses: actions/setup-go@v3 + with: + go-version: ${{ env.GO_VERSION }} + + - name: Checkout + uses: actions/checkout@v3 + with: + submodules: true + + - name: Setup K3d + uses: nolar/setup-k3d-k3s@v1.0.9 + with: + version: v1.20 + github-token: ${{ secrets.GITHUB_TOKEN }} + + - name: Definition Doc generate check + run: | + go build -o docgen hack/docgen/def/gen.go + ./docgen --type=comp --force-example-doc --path=./comp-def-check.md + ./docgen --type=trait --force-example-doc --path=./trait-def-check.md + ./docgen --type=wf --force-example-doc --path=./wf-def-check.md + ./docgen --type=policy --force-example-doc --path=./policy-def-check.md \ No newline at end of file diff --git a/hack/docgen/def/gen.go b/hack/docgen/def/gen.go index 2105aa791..59b128d46 100644 --- a/hack/docgen/def/gen.go +++ b/hack/docgen/def/gen.go @@ -42,6 +42,7 @@ func main() { defdir := flag.String("def-dir", "", "path of definition dir") tp := flag.String("type", "", "choose one of the definition to print") i18nfile := flag.String("i18n", "../kubevela.io/static/reference-i18n.json", "file path of i18n data") + forceExample := flag.Bool("force-example-doc", false, "example must be provided for definitions") flag.Parse() if *i18nfile != "" { @@ -52,21 +53,29 @@ func main() { fmt.Println("you must specify a type with definition ref path specified ") os.Exit(1) } + + opt := mods.Options{ + Path: *path, + Location: *location, + DefDir: *defdir, + ForceExamples: *forceExample, + } + fmt.Printf("creating docs with args path=%s, location=%s, defdir=%s, type=%s.\n", *path, *location, *defdir, *tp) switch types.CapType(*tp) { case types.TypeComponentDefinition, "component", "comp": - mods.ComponentDef(ctx, c, path, location, *defdir) + mods.ComponentDef(ctx, c, opt) case types.TypeTrait: - mods.TraitDef(ctx, c, path, location, *defdir) + mods.TraitDef(ctx, c, opt) case types.TypePolicy: - mods.PolicyDef(ctx, c, path, location, *defdir) + mods.PolicyDef(ctx, c, opt) case types.TypeWorkflowStep, "workflow", "wf": - mods.WorkflowDef(ctx, c, path, location, *defdir) + mods.WorkflowDef(ctx, c, opt) case "": - mods.ComponentDef(ctx, c, path, location, *defdir) - mods.TraitDef(ctx, c, path, location, *defdir) - mods.PolicyDef(ctx, c, path, location, *defdir) - mods.WorkflowDef(ctx, c, path, location, *defdir) + mods.ComponentDef(ctx, c, opt) + mods.TraitDef(ctx, c, opt) + mods.PolicyDef(ctx, c, opt) + mods.WorkflowDef(ctx, c, opt) default: fmt.Printf("type %s not supported\n", *tp) os.Exit(1) diff --git a/hack/docgen/def/mods/component.go b/hack/docgen/def/mods/component.go index fb29879af..82115fc8b 100644 --- a/hack/docgen/def/mods/component.go +++ b/hack/docgen/def/mods/component.go @@ -19,7 +19,6 @@ package mods import ( "context" "fmt" - "io/ioutil" "os" "strings" "time" @@ -60,12 +59,13 @@ title: 内置组件列表 ` + fmt.Sprintf("> 本文档由[脚本](../../contributor/cli-ref-doc)自动生成，请勿手动修改，上次更新于 %s。\n\n", time.Now().Format(time.RFC3339)) // ComponentDef generate component def reference doc -func ComponentDef(ctx context.Context, c common.Args, path, location *string, defdir string) { - if defdir == "" { - defdir = ComponentDefDir +func ComponentDef(ctx context.Context, c common.Args, opt Options) { + if opt.DefDir == "" { + opt.DefDir = ComponentDefDir } ref := &docgen.MarkdownReference{ - AllInOne: true, + AllInOne: true, + ForceExample: opt.ForceExamples, Filter: func(capability types.Capability) bool { if capability.Type != types.TypeComponentDefinition || capability.Category != types.CUECategory { return false @@ -74,9 +74,9 @@ func ComponentDef(ctx context.Context, c common.Args, path, location *string, de return false } // only print capability which contained in cue def - files, err := ioutil.ReadDir(defdir) + files, err := os.ReadDir(opt.DefDir) if err != nil { - fmt.Println("read dir err", defdir, err) + fmt.Println("read dir err", opt.DefDir, err) return false } for _, f := range files { @@ -96,19 +96,20 @@ func ComponentDef(ctx context.Context, c common.Args, path, location *string, de return } ref.DiscoveryMapper = dm - if *path != "" { + if opt.Path != "" { ref.I18N = &docgen.En - if strings.Contains(*location, "zh") || strings.Contains(*location, "chinese") { + if strings.Contains(opt.Location, "zh") || strings.Contains(opt.Location, "chinese") { ref.I18N = &docgen.Zh ref.CustomDocHeader = CustomComponentHeaderZH } - if err := ref.GenerateReferenceDocs(ctx, c, *path); err != nil { + if err := ref.GenerateReferenceDocs(ctx, c, opt.Path); err != nil { fmt.Println(err) os.Exit(1) } - fmt.Printf("component reference docs (%s) successfully generated in %s \n", ref.I18N.Language(), *path) + fmt.Printf("component reference docs (%s) successfully generated in %s \n", ref.I18N.Language(), opt.Path) + return } - if *location == "" || *location == "en" { + if opt.Location == "" || opt.Location == "en" { ref.I18N = &docgen.En if err := ref.GenerateReferenceDocs(ctx, c, ComponentDefRefPath); err != nil { fmt.Println(err) @@ -116,7 +117,7 @@ func ComponentDef(ctx context.Context, c common.Args, path, location *string, de } fmt.Printf("component reference docs (%s) successfully generated in %s \n", ref.I18N.Language(), ComponentDefRefPath) } - if *location == "" || *location == "zh" { + if opt.Location == "" || opt.Location == "zh" { ref.I18N = &docgen.Zh ref.CustomDocHeader = CustomComponentHeaderZH if err := ref.GenerateReferenceDocs(ctx, c, ComponentDefRefPathZh); err != nil { diff --git a/hack/docgen/def/mods/policy.go b/hack/docgen/def/mods/policy.go index 8f0182458..375d8bfc6 100644 --- a/hack/docgen/def/mods/policy.go +++ b/hack/docgen/def/mods/policy.go @@ -19,7 +19,6 @@ package mods import ( "context" "fmt" - "io/ioutil" "os" "strings" "time" @@ -58,12 +57,13 @@ title: 内置策略列表 ` + fmt.Sprintf("> 本文档由[脚本](../../contributor/cli-ref-doc)自动生成，请勿手动修改，上次更新于 %s。\n\n", time.Now().Format(time.RFC3339)) // PolicyDef generate policy def reference doc -func PolicyDef(ctx context.Context, c common.Args, path, location *string, defdir string) { - if defdir == "" { - defdir = PolicyDefDir +func PolicyDef(ctx context.Context, c common.Args, opt Options) { + if opt.DefDir == "" { + opt.DefDir = PolicyDefDir } ref := &docgen.MarkdownReference{ - AllInOne: true, + AllInOne: true, + ForceExample: opt.ForceExamples, Filter: func(capability types.Capability) bool { if capability.Type != types.TypePolicy || capability.Category != types.CUECategory { return false @@ -72,9 +72,9 @@ func PolicyDef(ctx context.Context, c common.Args, path, location *string, defdi return false } // only print capability which contained in cue def - files, err := ioutil.ReadDir(defdir) + files, err := os.ReadDir(opt.DefDir) if err != nil { - fmt.Println("read dir err", defdir, err) + fmt.Println("read dir err", opt.DefDir, err) return false } for _, f := range files { @@ -86,20 +86,21 @@ func PolicyDef(ctx context.Context, c common.Args, path, location *string, defdi }, CustomDocHeader: CustomPolicyHeaderEN, } - ref.Remote = &docgen.FromCluster{Namespace: types.DefaultKubeVelaNS} - if *path != "" { + ref.Local = &docgen.FromLocal{Path: PolicyDefDir} + if opt.Path != "" { ref.I18N = &docgen.En - if strings.Contains(*location, "zh") || strings.Contains(*location, "chinese") { + if strings.Contains(opt.Location, "zh") || strings.Contains(opt.Location, "chinese") { ref.I18N = &docgen.Zh ref.CustomDocHeader = CustomPolicyHeaderZH } - if err := ref.GenerateReferenceDocs(ctx, c, *path); err != nil { + if err := ref.GenerateReferenceDocs(ctx, c, opt.Path); err != nil { fmt.Println(err) os.Exit(1) } - fmt.Printf("policy reference docs (%s) successfully generated in %s \n", ref.I18N.Language(), *path) + fmt.Printf("policy reference docs (%s) successfully generated in %s \n", ref.I18N.Language(), opt.Path) + return } - if *location == "" || *location == "en" { + if opt.Location == "" || opt.Location == "en" { ref.I18N = &docgen.En if err := ref.GenerateReferenceDocs(ctx, c, PolicyDefRefPath); err != nil { fmt.Println(err) @@ -107,7 +108,7 @@ func PolicyDef(ctx context.Context, c common.Args, path, location *string, defdi } fmt.Printf("policy reference docs (%s) successfully generated in %s \n", ref.I18N.Language(), PolicyDefRefPath) } - if *location == "" || *location == "zh" { + if opt.Location == "" || opt.Location == "zh" { ref.I18N = &docgen.Zh ref.CustomDocHeader = CustomPolicyHeaderZH if err := ref.GenerateReferenceDocs(ctx, c, PolicyDefRefPathZh); err != nil { diff --git a/hack/docgen/def/mods/trait.go b/hack/docgen/def/mods/trait.go index 90ccc4143..92acc8eb8 100644 --- a/hack/docgen/def/mods/trait.go +++ b/hack/docgen/def/mods/trait.go @@ -19,7 +19,6 @@ package mods import ( "context" "fmt" - "io/ioutil" "os" "strings" "time" @@ -58,12 +57,13 @@ title: 内置运维特征列表 ` + fmt.Sprintf("> 本文档由[脚本](../../contributor/cli-ref-doc)自动生成，请勿手动修改，上次更新于 %s。\n\n", time.Now().Format(time.RFC3339)) // TraitDef generate trait def reference doc -func TraitDef(ctx context.Context, c common.Args, path, location *string, defdir string) { - if defdir == "" { - defdir = TraitDefDir +func TraitDef(ctx context.Context, c common.Args, opt Options) { + if opt.DefDir == "" { + opt.DefDir = TraitDefDir } ref := &docgen.MarkdownReference{ - AllInOne: true, + AllInOne: true, + ForceExample: opt.ForceExamples, Filter: func(capability types.Capability) bool { if capability.Type != types.TypeTrait || capability.Category != types.CUECategory { return false @@ -72,9 +72,9 @@ func TraitDef(ctx context.Context, c common.Args, path, location *string, defdir return false } // only print capability which contained in cue def - files, err := ioutil.ReadDir(defdir) + files, err := os.ReadDir(opt.DefDir) if err != nil { - fmt.Println("read dir err", defdir, err) + fmt.Println("read dir err", opt.DefDir, err) return false } for _, f := range files { @@ -90,20 +90,20 @@ func TraitDef(ctx context.Context, c common.Args, path, location *string, defdir Path: TraitDefDir, } - if *path != "" { + if opt.Path != "" { ref.I18N = &docgen.En - if strings.Contains(*location, "zh") || strings.Contains(*location, "chinese") { + if strings.Contains(opt.Location, "zh") || strings.Contains(opt.Location, "chinese") { ref.I18N = &docgen.Zh ref.CustomDocHeader = CustomTraitHeaderZH } - if err := ref.GenerateReferenceDocs(ctx, c, *path); err != nil { + if err := ref.GenerateReferenceDocs(ctx, c, opt.Path); err != nil { fmt.Println(err) os.Exit(1) } - fmt.Printf("trait reference docs (%s) successfully generated in %s \n", ref.I18N.Language(), *path) + fmt.Printf("trait reference docs (%s) successfully generated in %s \n", ref.I18N.Language(), opt.Path) } else { // Generate to default path depends on language - if *location == "" || *location == "en" { + if opt.Location == "" || opt.Location == "en" { ref.I18N = &docgen.En if err := ref.GenerateReferenceDocs(ctx, c, TraitDefRefPath); err != nil { fmt.Println(err) @@ -111,7 +111,7 @@ func TraitDef(ctx context.Context, c common.Args, path, location *string, defdir } fmt.Printf("trait reference docs (%s) successfully generated in %s \n", ref.I18N.Language(), TraitDefRefPath) } - if *location == "" || *location == "zh" { + if opt.Location == "" || opt.Location == "zh" { ref.I18N = &docgen.Zh ref.CustomDocHeader = CustomTraitHeaderZH if err := ref.GenerateReferenceDocs(ctx, c, TraitDefRefPathZh); err != nil { diff --git a/hack/docgen/def/mods/types.go b/hack/docgen/def/mods/types.go new file mode 100644 index 000000000..fccc35255 --- /dev/null +++ b/hack/docgen/def/mods/types.go @@ -0,0 +1,25 @@ +/* + Copyright 2022 The KubeVela 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 mods + +// Options defines the doc generate options +type Options struct { + Path string + Location string + DefDir string + ForceExamples bool +} diff --git a/hack/docgen/def/mods/workflow.go b/hack/docgen/def/mods/workflow.go index 14a994ec7..5616e519d 100644 --- a/hack/docgen/def/mods/workflow.go +++ b/hack/docgen/def/mods/workflow.go @@ -19,7 +19,6 @@ package mods import ( "context" "fmt" - "io/ioutil" "os" "strings" "time" @@ -58,12 +57,13 @@ title: 内置工作流步骤列表 ` + fmt.Sprintf("> 本文档由[脚本](../../contributor/cli-ref-doc)自动生成，请勿手动修改，上次更新于 %s。\n\n", time.Now().Format(time.RFC3339)) // WorkflowDef generate workflow def reference doc -func WorkflowDef(ctx context.Context, c common.Args, path, location *string, defdir string) { - if defdir == "" { - defdir = WorkflowDefDir +func WorkflowDef(ctx context.Context, c common.Args, opt Options) { + if opt.DefDir == "" { + opt.DefDir = WorkflowDefDir } ref := &docgen.MarkdownReference{ - AllInOne: true, + AllInOne: true, + ForceExample: opt.ForceExamples, Filter: func(capability types.Capability) bool { if capability.Type != types.TypeWorkflowStep || capability.Category != types.CUECategory { @@ -74,9 +74,9 @@ func WorkflowDef(ctx context.Context, c common.Args, path, location *string, def return false } // only print capability which contained in cue def - files, err := ioutil.ReadDir(defdir) + files, err := os.ReadDir(opt.DefDir) if err != nil { - fmt.Println("read dir err", defdir, err) + fmt.Println("read dir err", opt.DefDir, err) return false } for _, f := range files { @@ -88,21 +88,22 @@ func WorkflowDef(ctx context.Context, c common.Args, path, location *string, def }, CustomDocHeader: CustomWorkflowHeaderEN, } - ref.Remote = &docgen.FromCluster{Namespace: types.DefaultKubeVelaNS} + ref.Local = &docgen.FromLocal{Path: WorkflowDefDir} - if *path != "" { + if opt.Path != "" { ref.I18N = &docgen.En - if strings.Contains(*location, "zh") || strings.Contains(*location, "chinese") { + if strings.Contains(opt.Location, "zh") || strings.Contains(opt.Location, "chinese") { ref.I18N = &docgen.Zh ref.CustomDocHeader = CustomWorkflowHeaderZH } - if err := ref.GenerateReferenceDocs(ctx, c, *path); err != nil { + if err := ref.GenerateReferenceDocs(ctx, c, opt.Path); err != nil { fmt.Println(err) os.Exit(1) } - fmt.Printf("workflow reference docs (%s) successfully generated in %s \n", ref.I18N.Language(), *path) + fmt.Printf("workflow reference docs (%s) successfully generated in %s \n", ref.I18N.Language(), opt.Path) + return } - if *location == "" || *location == "en" { + if opt.Location == "" || opt.Location == "en" { ref.I18N = &docgen.En if err := ref.GenerateReferenceDocs(ctx, c, WorkflowDefRefPath); err != nil { fmt.Println(err) @@ -110,7 +111,7 @@ func WorkflowDef(ctx context.Context, c common.Args, path, location *string, def } fmt.Printf("workflow reference docs (%s) successfully generated in %s \n", ref.I18N.Language(), WorkflowDefRefPath) } - if *location == "" || *location == "zh" { + if opt.Location == "" || opt.Location == "zh" { ref.I18N = &docgen.Zh ref.CustomDocHeader = CustomWorkflowHeaderZH if err := ref.GenerateReferenceDocs(ctx, c, WorkflowDefRefPathZh); err != nil { diff --git a/references/docgen/def-doc/policy/health.eg.md b/references/docgen/def-doc/policy/health.eg.md new file mode 100644 index 000000000..4f6469eff --- /dev/null +++ b/references/docgen/def-doc/policy/health.eg.md @@ -0,0 +1,23 @@ +```yaml +apiVersion: core.oam.dev/v1beta1 +kind: Application +metadata: + name: example-app-rollout + namespace: default +spec: + components: + - name: hello-world-server + type: webservice + properties: + image: crccheck/hello-world + ports: + - port: 8000 + expose: true + type: webservice + policies: + - name: health-policy-demo + type: health + properties: + probeInterval: 5 + probeTimeout: 10 +``` \ No newline at end of file diff --git a/references/docgen/def-doc/trait/affinity.eg.md b/references/docgen/def-doc/trait/affinity.eg.md new file mode 100644 index 000000000..ae121d36e --- /dev/null +++ b/references/docgen/def-doc/trait/affinity.eg.md @@ -0,0 +1,29 @@ +```yaml +apiVersion: core.oam.dev/v1beta1 +kind: Application +metadata: + name: busybox +spec: + components: + - name: busybox + type: webservice + properties: + image: busybox + cmd: ["sleep", "86400"] + labels: + label-key: label-value + to-delete-label-key: to-delete-label-value + traits: + - type: affinity + properties: + podAffinity: + preferred: + - weight: 1 + podAffinityTerm: + labelSelector: + matchExpressions: + - key: "secrity" + values: ["S1"] + namespaces: ["default"] + topologyKey: "kubernetes.io/hostname" +``` \ No newline at end of file diff --git a/references/docgen/def-doc/trait/json-merge-patch.eg.md b/references/docgen/def-doc/trait/json-merge-patch.eg.md new file mode 100644 index 000000000..f310f291e --- /dev/null +++ b/references/docgen/def-doc/trait/json-merge-patch.eg.md @@ -0,0 +1,41 @@ +```yaml +apiVersion: core.oam.dev/v1beta1 +kind: Application +metadata: + name: busybox +spec: + components: + - name: busybox + type: webservice + properties: + image: busybox + cmd: ["sleep", "86400"] + labels: + pod-label-key: pod-label-value + to-delete-label-key: to-delete-label-value + traits: + # the json merge patch can be used to add, replace and delete fields + # the following part will + # 1. add `deploy-label-key` to deployment labels + # 2. set deployment replicas to 3 + # 3. set `pod-label-key` to `pod-label-modified-value` in pod labels + # 4. delete `to-delete-label-key` in pod labels + # 5. reset `containers` for pod + - type: json-merge-patch + properties: + metadata: + labels: + deploy-label-key: deploy-label-added-value + spec: + replicas: 3 + template: + metadata: + labels: + pod-label-key: pod-label-modified-value + to-delete-label-key: null + spec: + containers: + - name: busybox-new + image: busybox:1.34 + command: ["sleep", "864000"] +``` \ No newline at end of file diff --git a/references/docgen/def-doc/trait/json-patch.eg.md b/references/docgen/def-doc/trait/json-patch.eg.md new file mode 100644 index 000000000..26e428d37 --- /dev/null +++ b/references/docgen/def-doc/trait/json-patch.eg.md @@ -0,0 +1,41 @@ +```yaml +apiVersion: core.oam.dev/v1beta1 +kind: Application +metadata: + name: busybox +spec: + components: + - name: busybox + type: webservice + properties: + image: busybox + cmd: ["sleep", "86400"] + labels: + pod-label-key: pod-label-value + to-delete-label-key: to-delete-label-value + traits: + # the json patch can be used to add, replace and delete fields + # the following part will + # 1. add `deploy-label-key` to deployment labels + # 2. set deployment replicas to 3 + # 3. set `pod-label-key` to `pod-label-modified-value` in pod labels + # 4. delete `to-delete-label-key` in pod labels + # 5. add sidecar container for pod + - type: json-patch + properties: + operations: + - op: add + path: "/spec/replicas" + value: 3 + - op: replace + path: "/spec/template/metadata/labels/pod-label-key" + value: pod-label-modified-value + - op: remove + path: "/spec/template/metadata/labels/to-delete-label-key" + - op: add + path: "/spec/template/spec/containers/1" + value: + name: busybox-sidecar + image: busybox:1.34 + command: ["sleep", "864000"] +``` \ No newline at end of file diff --git a/references/docgen/def-doc/trait/topologyspreadconstraints.eg.md b/references/docgen/def-doc/trait/topologyspreadconstraints.eg.md new file mode 100644 index 000000000..e8d00af0a --- /dev/null +++ b/references/docgen/def-doc/trait/topologyspreadconstraints.eg.md @@ -0,0 +1,40 @@ +```yaml +apiVersion: core.oam.dev/v1beta1 +kind: Application +metadata: + name: application-with-topologyspreadconstraints +spec: + components: + - name: busybox-runner + type: worker + properties: + image: busybox + cmd: + - sleep + - '1000' + traits: + - type: topologyspreadconstraints + properties: + constraints: + - topologyKey: zone + labelSelector: + matchLabels: + zone: us-east-1a + maxSkew: 1 + whenUnsatisfiable: DoNotSchedule + minDomains: 1 + nodeAffinityPolicy: Ignore + nodeTaintsPolicy: Ignore + - topologyKey: node + labelSelector: + matchExpressions: + - key: foo + operator: In + values: + - abc + maxSkew: 1 + whenUnsatisfiable: ScheduleAnyway + minDomains: 1 + nodeAffinityPolicy: Ignore + nodeTaintsPolicy: Ignore +``` \ No newline at end of file diff --git a/references/docgen/def-doc/workflowstep/create-config.eg.md b/references/docgen/def-doc/workflowstep/create-config.eg.md new file mode 100644 index 000000000..c655124df --- /dev/null +++ b/references/docgen/def-doc/workflowstep/create-config.eg.md @@ -0,0 +1,32 @@ +```yaml +kind: Application +apiVersion: core.oam.dev/v1beta1 +metadata: + name: test-config + namespace: "config-e2e-test" +spec: + components: [] + workflow: + steps: + - name: write-config + type: create-config + properties: + name: test + config: + key1: value1 + key2: 2 + key3: true + key4: + key5: value5 + - name: read-config + type: read-config + properties: + name: test + outputs: + - fromKey: config + name: read-config + - name: delete-config + type: delete-config + properties: + name: test +``` \ No newline at end of file diff --git a/references/docgen/def-doc/workflowstep/delete-config.eg.md b/references/docgen/def-doc/workflowstep/delete-config.eg.md new file mode 100644 index 000000000..001db0bbd --- /dev/null +++ b/references/docgen/def-doc/workflowstep/delete-config.eg.md @@ -0,0 +1,25 @@ +```yaml +kind: Application +apiVersion: core.oam.dev/v1beta1 +metadata: + name: test-config + namespace: "config-e2e-test" +spec: + components: [] + workflow: + steps: + - name: write-config + type: create-config + properties: + name: test + config: + key1: value1 + key2: 2 + key3: true + key4: + key5: value5 + - name: delete-config + type: delete-config + properties: + name: test +``` \ No newline at end of file diff --git a/references/docgen/def-doc/workflowstep/deploy-cloud-resource.eg.md b/references/docgen/def-doc/workflowstep/deploy-cloud-resource.eg.md new file mode 100644 index 000000000..b7299ed23 --- /dev/null +++ b/references/docgen/def-doc/workflowstep/deploy-cloud-resource.eg.md @@ -0,0 +1,80 @@ +```yaml +apiVersion: core.oam.dev/v1beta1 +kind: Application +metadata: + name: rds-app + namespace: project-1 +spec: + components: + - name: db + type: alibaba-rds + properties: + instance_name: db + account_name: kubevela + password: my-password + writeConnectionSecretToRef: + name: project-1-rds-conn-credential + policies: + - name: env-policy + type: env-binding + properties: + envs: + # 部署 RDS 给杭州集群 + - name: hangzhou + placement: + clusterSelector: + name: cluster-hangzhou + patch: + components: + - name: db + type: alibaba-rds + properties: + # region: hangzhou + instance_name: hangzhou_db + # 部署 RDS 给香港集群 + - name: hongkong + placement: + clusterSelector: + name: cluster-hongkong + namespaceSelector: + name: hk-project-1 + patch: + components: + - name: db + type: alibaba-rds + properties: + # region: hongkong + instance_name: hongkong_db + writeConnectionSecretToRef: + name: hk-project-rds-credential + + workflow: + steps: + # 部署 RDS 给杭州区用 + - name: deploy-hangzhou-rds + type: deploy-cloud-resource + properties: + env: hangzhou + # 将给杭州区用的 RDS 共享给北京区 + - name: share-hangzhou-rds-to-beijing + type: share-cloud-resource + properties: + env: hangzhou + placements: + - cluster: cluster-beijing + # 部署 RDS 给香港区用 + - name: deploy-hongkong-rds + type: deploy-cloud-resource + properties: + env: hongkong + # 将给香港区用的 RDS 共享给香港区其他项目用 + - name: share-hongkong-rds-to-other-namespace + type: share-cloud-resource + properties: + env: hongkong + placements: + - cluster: cluster-hongkong + namespace: hk-project-2 + - cluster: cluster-hongkong + namespace: hk-project-3 +``` \ No newline at end of file diff --git a/references/docgen/def-doc/workflowstep/generate-jdbc-connection.eg.md b/references/docgen/def-doc/workflowstep/generate-jdbc-connection.eg.md new file mode 100644 index 000000000..fe058d9e6 --- /dev/null +++ b/references/docgen/def-doc/workflowstep/generate-jdbc-connection.eg.md @@ -0,0 +1,42 @@ +```yaml +apiVersion: core.oam.dev/v1beta1 +kind: Application +metadata: + name: jdbc +spec: + components: + - name: db + type: alibaba-rds + properties: + instance_name: favorite-links + database_name: db1 + account_name: oamtest + password: U34rfwefwefffaked + security_ips: [ "0.0.0.0/0" ] + privilege: ReadWrite + writeConnectionSecretToRef: + name: db-conn + - name: express-server + type: webservice + properties: + image: crccheck/hello-world + port: 8000 + + workflow: + steps: + - name: jdbc + type: generate-jdbc-connection + outputs: + - name: jdbc + valueFrom: jdbc + properties: + name: db-conn + namespace: default + - name: apply + type: apply-component + inputs: + - from: jdbc + parameterKey: env + properties: + component: express-server +``` \ No newline at end of file diff --git a/references/docgen/def-doc/workflowstep/list-config.eg.md b/references/docgen/def-doc/workflowstep/list-config.eg.md new file mode 100644 index 000000000..af344a479 --- /dev/null +++ b/references/docgen/def-doc/workflowstep/list-config.eg.md @@ -0,0 +1,50 @@ +```yaml +apiVersion: core.oam.dev/v1alpha1 +kind: WorkflowRun +metadata: + name: observability + namespace: vela-system +spec: + context: + readConfig: true + mode: + workflowSpec: + steps: + - name: Enable Prism + type: addon-operation + properties: + addonName: vela-prism + + - name: Enable o11y + type: addon-operation + properties: + addonName: o11y-definitions + operation: enable + args: + - --override-definitions + + - name: Prepare Prometheus + type: step-group + subSteps: + - name: get-exist-prometheus + type: list-config + properties: + template: prometheus-server + outputs: + - name: prometheus + valueFrom: "output.configs" + + - name: prometheus-server + inputs: + - from: prometheus + # TODO: Make it is not required + parameterKey: configs + if: "!context.readConfig || len(inputs.prometheus) == 0" + type: addon-operation + properties: + addonName: prometheus-server + operation: enable + args: + - memory=4096Mi + - serviceType=LoadBalancer +``` \ No newline at end of file diff --git a/references/docgen/def-doc/workflowstep/read-config.eg.md b/references/docgen/def-doc/workflowstep/read-config.eg.md new file mode 100644 index 000000000..abd7afb57 --- /dev/null +++ b/references/docgen/def-doc/workflowstep/read-config.eg.md @@ -0,0 +1,18 @@ +```yaml +kind: Application +apiVersion: core.oam.dev/v1beta1 +metadata: + name: test-config + namespace: "config-e2e-test" +spec: + components: [] + workflow: + steps: + - name: read-config + type: read-config + properties: + name: test + outputs: + - fromKey: config + name: read-config +``` \ No newline at end of file diff --git a/references/docgen/def-doc/workflowstep/share-cloud-resource.eg.md b/references/docgen/def-doc/workflowstep/share-cloud-resource.eg.md new file mode 100644 index 000000000..b7299ed23 --- /dev/null +++ b/references/docgen/def-doc/workflowstep/share-cloud-resource.eg.md @@ -0,0 +1,80 @@ +```yaml +apiVersion: core.oam.dev/v1beta1 +kind: Application +metadata: + name: rds-app + namespace: project-1 +spec: + components: + - name: db + type: alibaba-rds + properties: + instance_name: db + account_name: kubevela + password: my-password + writeConnectionSecretToRef: + name: project-1-rds-conn-credential + policies: + - name: env-policy + type: env-binding + properties: + envs: + # 部署 RDS 给杭州集群 + - name: hangzhou + placement: + clusterSelector: + name: cluster-hangzhou + patch: + components: + - name: db + type: alibaba-rds + properties: + # region: hangzhou + instance_name: hangzhou_db + # 部署 RDS 给香港集群 + - name: hongkong + placement: + clusterSelector: + name: cluster-hongkong + namespaceSelector: + name: hk-project-1 + patch: + components: + - name: db + type: alibaba-rds + properties: + # region: hongkong + instance_name: hongkong_db + writeConnectionSecretToRef: + name: hk-project-rds-credential + + workflow: + steps: + # 部署 RDS 给杭州区用 + - name: deploy-hangzhou-rds + type: deploy-cloud-resource + properties: + env: hangzhou + # 将给杭州区用的 RDS 共享给北京区 + - name: share-hangzhou-rds-to-beijing + type: share-cloud-resource + properties: + env: hangzhou + placements: + - cluster: cluster-beijing + # 部署 RDS 给香港区用 + - name: deploy-hongkong-rds + type: deploy-cloud-resource + properties: + env: hongkong + # 将给香港区用的 RDS 共享给香港区其他项目用 + - name: share-hongkong-rds-to-other-namespace + type: share-cloud-resource + properties: + env: hongkong + placements: + - cluster: cluster-hongkong + namespace: hk-project-2 + - cluster: cluster-hongkong + namespace: hk-project-3 +``` \ No newline at end of file diff --git a/references/docgen/markdown.go b/references/docgen/markdown.go index a3c0f7f03..bcd17172e 100644 --- a/references/docgen/markdown.go +++ b/references/docgen/markdown.go @@ -47,6 +47,7 @@ const AllComponentTypes = "*" type MarkdownReference struct { Filter func(types.Capability) bool AllInOne bool + ForceExample bool CustomDocHeader string DiscoveryMapper discoverymapper.DiscoveryMapper ParseReference @@ -255,6 +256,9 @@ func (ref *MarkdownReference) GenerateMarkdownForCap(ctx context.Context, c type if sampleContent != "" { sample = fmt.Sprintf("\n\n%s %s\n\n%s", sharp, exampleTitle, sampleContent) + } else if ref.ForceExample { + fmt.Printf("You must provide example doc for the new added definition \"%s\", place the example doc in the /refereces/docgen/def-doc folders, for more details refer to https://kubevela.io/docs/contributor/cli-ref-doc#how-the-docs-generated", capName) + os.Exit(1) } if c.Category == types.CUECategory && baseDoc != "" { base = fmt.Sprintf("\n\n%s %s\n\n%s", sharp, baseTitle, baseDoc)