Update Reference Docs

This guide is an introduction of how to generate docs automatically from Golang scripts.

This section introduce how to update CLI reference doc in the website. The whole process was done by script automatically. You need to follow this guide to build your environment.

  1. step up these two projects in the same folder.
  1. $ tree -L 1
  2. .
  3. ├── kubevela
  4. └── kubevela.io
  1. Run generate command in kubevela root dir.
  1. cd kubevela/
  2. go run ./hack/docgen/cli/gen.go
  1. Update more docs such as i18n zh
  1. go run ./hack/docgen/cli/gen.go ../kubevela.io/i18n/zh/docusaurus-plugin-content-docs/current/cli
  1. Then you can check the difference in kubevela.io.
  1. cd ../kubevela.io
  2. git status
  1. Check in the changes and send pull request.

This section introduce how to definition reference docs in the website, including:

Most of the steps are done by script automatically. You need to follow this guide to build your environment.

By default, the following steps will update for all definition reference at a time. Just follow these steps.

  1. step up these two projects in the same folder.
  1. $ tree -L 1
  2. .
  3. ├── kubevela
  4. └── kubevela.io
  1. Run generate command in kubevela root dir.
  1. cd kubevela/
  2. go run hack/docgen/def/gen.go
  1. Then you can check the difference in kubevela.io.
  1. cd ../kubevela.io
  2. git status
  1. Check in the changes and send pull request.

That’s finished for the general update.

You can specify some args for more flexible usage.

  • Generate only for specified type
  1. go run hack/docgen/def/gen.go --type component
  2. go run hack/docgen/def/gen.go --type trait
  3. go run hack/docgen/def/gen.go --type policy
  4. go run hack/docgen/def/gen.go --type workflowstep
  • Specify a path for output

You must choose one of the type generated if path specified.

  1. go run hack/docgen/def/gen.go --type component --path ../kubevela.io/docs/end-user/components/references.md
  • Specify the i18n location with a translation script data for the output
  1. go run hack/docgen/def/gen.go --location zh --i18n ../kubevela.io/static/reference-i18n.json
  3. go run hack/docgen/def/gen.go --location zh --i18n https://kubevela.io/reference-i18n.json
  5. go run hack/docgen/def/gen.go --type component --path ../kubevela.io/docs/end-user/components/references.md --location zh --i18n ../kubevela.io/static/reference-i18n.json
  1. Load definitions from Kubernetes.

The script will load all definitions from your Kubernetes Cluster, so you need to apply all built-in definitions before run.

  1. Compare the internal definition folder in the project.

Besides the server side definitions, the script will also compare the cue files in the KubeVela project. Only definitions existing in these folders will be generated as reference docs.

  1. $ tree ./vela-templates/definitions/internal
  2. vela-templates/definitions/internal
  3. ├── component
  4. │   ├── config-image-registry.cue
  5. │   ├── ...
  6. │   └── worker.cue
  7. ├── policy
  8. │   ├── health.cue
  9. │   ├── override.cue
  10. │   └── topology.cue
  11. ├── trait
  12. │   ├── affinity.cue
  13. │   ├── ...
  14. │   └── storage.cue
  15. └── workflowstep
  16.     ├── apply-application-in-parallel.cue
  17.     ├── ...
  18.     └── webhook.cue
  20. 4 directories, 53 files
  1. Generate Examples.

By default, the definition don’t contain any examples, maintainers can specify example for the built-in definitions.

The docs folder will be embedded into CLI binary, you must write into the following hierarchy:

  1. $ tree references/plugins/def-doc
  2. references/plugins/def-doc
  3. ├── component
  4. │   ├── webservice.eg.md
  5. │   ├── webservice.param.md
  6. │   ├── webservice.desc.md
  7. │   ├── ...
  8. │   └── worker.eg.md
  9. └── trait
  10.     ├── annotations.eg.md
  11.     ├── ...
  12.     └── sidecar.eg.md
  14. 2 directories, 21 files

The file name MUST has the same name with the definition, along with the suffix:

  • The example of definition MUST has suffix .eg.md and write in markdown format.
  • The parameter(specification) of definition MUST has suffix .param.md, if exists, it will override the one auto-generated from definition parameters.
  • The description of definition MUST has suffix .desc.md, if exists, it will override the one auto-generated from definition annotation.

This section introduce how to update terraform based cloud resource reference doc in the website.

Most of the steps are done by script automatically. You need to follow this guide to build your environment.

  1. step up these two projects in the same folder.
  1. $ tree -L 1
  2. .
  3. ├── kubevela
  4. └── kubevela.io
  1. Run generate command in kubevela root dir.
  1. cd kubevela/
  2. go run ./hack/docgen/terraform/generate.go --i18n ../kubevela.io/static/reference-i18n.json
  1. Update the resource catalog list if there’re new cloud resources
  • Resource Catalog(English): kubevela.io/docs/end-user/components/cloud-services/cloud-resources-list.md
  • Resource Catalog(Chinese): kubevela.io/i18n/zh/docusaurus-plugin-content-docs/current/end-user/components/cloud-services/cloud-resources-list.md
  1. Then you can check the difference in kubevela.io.
  1. cd ../kubevela.io
  2. git status
  1. Check in the changes and send pull request.

You need to translate into this file if you want to contribute for internationalization(i18n):

After any translate, run the commands above to update all these reference docs.

Last updated on 2023年2月9日 by dependabot[bot]