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. Run generate command in kubevela root dir.
    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. 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 can specify some args for more flexible usage.

    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
    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
    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. Generate Examples.

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

    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.     ├── ...
    13. 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 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.