Merge pull request #403 from Peefy/docs-update-090-cli-ref

docs: update cli 0.9 reference docs

Author: Peefy

docs/tools/cli/kcl/docgen.md

@@ -137,6 +137,9 @@ Examples:
   # Generate Markdown document for current package
   kcl doc generate
 
+  # Generate Markdown document for current package and escape the HTML symbols | to \|, \n to <br>, etc.
+  kcl doc generate --escape-html
+
   # Generate Html document for current package
   kcl doc generate --format html
 

docs/tools/cli/kcl/import.md

@@ -16,6 +16,7 @@ This command converts other formats to KCL file.
 Supported conversion modes:
 - json:            convert JSON data to KCL data
 - yaml:            convert YAML data to KCL data
+- toml:            convert TOML data to KCL data
 - gostruct:        convert Go struct to KCL schema
 - jsonschema:      convert JSON schema to KCL schema
 - terraformschema: convert Terraform schema to KCL schema
@@ -39,6 +40,9 @@ Examples:
   # Generate KCL models from YAML
   kcl import data.yaml
 
+  # Generate KCL models from TOML
+  kcl import data.toml
+
   # Generate KCL models from JSON Schema
   kcl import -m jsonschema schema.json
 
@@ -48,7 +52,6 @@ Examples:
   # Generate KCL models from Go structs
   kcl import -m gostruct schema.go
 
-
 Flags:
   -f, --force             Force overwrite output file
   -h, --help              help for import

docs/tools/cli/kcl/run.md

@@ -26,6 +26,9 @@ Examples:
   # Run a single file and output JSON
   kcl run path/to/kcl.k --format json
 
+  # Run a single file and output TOML
+  kcl run path/to/kcl.k --format toml
+
   # Run multiple files
   kcl run path/to/kcl1.k path/to/kcl2.k
 

docs/tools/cli/package-management/command-reference/1.init.md

@@ -43,3 +43,30 @@ kcl mod init
 # init a kcl package with a name 'my_package'
 kcl mod init my_package
 ```
+
+## Reference
+
+```shell
+This command initializes new kcl module in current directory.
+
+Usage:
+  kcl mod init [flags]
+
+Examples:
+  kcl mod init <command> [arguments]...
+  # Init one kcl module with the current folder name
+  kcl mod init
+  
+  # Init one kcl module with the name
+  kcl mod init package-name
+
+  # Init one kcl module with the name and version
+  kcl mod init package-name --version 0.1.0
+
+Flags:
+  -h, --help             help for init
+      --version string   init module version
+
+Global Flags:
+  -q, --quiet   Set the quiet mode (no output)
+```

docs/tools/cli/package-management/command-reference/11.update.md

@@ -33,3 +33,26 @@ kcl mod update
 ```shell
 kcl mod update path/to/package
 ```
+
+## Reference
+
+```shell
+This command updates dependencies listed in kcl.mod.lock based on kcl.mod.
+
+Usage:
+  kcl mod update [flags]
+
+Examples:
+  # Update the current module
+  kcl mod update
+  
+  # Update the module with the specified path
+  kcl mod update path/to/package
+
+Flags:
+  -h, --help           help for update
+      --no_sum_check   do not check the checksum of the package and update kcl.mod.lock
+
+Global Flags:
+  -q, --quiet   Set the quiet mode (no output)
+```

docs/tools/cli/package-management/command-reference/12.graph.md

@@ -25,3 +25,23 @@ Show help for `kcl mod graph` command.
 ```shell
 kcl mod graph
 ```
+
+## Reference
+
+```shell
+This command prints the module dependency graph.
+Each module is identified as a string of the form path@version.
+
+Usage:
+  kcl mod graph [flags]
+
+Examples:
+  # Print the current module dependency graph.
+  kcl mod graph
+
+Flags:
+  -h, --help   help for graph
+
+Global Flags:
+  -q, --quiet   Set the quiet mode (no output)
+```

docs/tools/cli/package-management/command-reference/2.add.md

@@ -46,8 +46,55 @@ kcl mod add k8s:1.29
 
 ### Add a dependency from git repository
 
-Add kcl dependency named `konfig` with version `v0.1.0` from git repository.
+Add kcl dependency named `konfig` with version `v0.4.0` from git repository.
 
 ```shell
-kcl mod add --git https://github.com/awesome-kusion/konfig.git --tag v0.1.0
+kcl mod add --git https://github.com/kcl-lang/konfig.git --tag v0.4.0
+```
+
+## Reference
+
+```shell
+This command adds new dependency
+
+Usage:
+  kcl mod add [flags]
+
+Examples:
+  # Add the module dependency named "k8s"
+  kcl mod add k8s
+
+  # Add the module dependency named "k8s" with the version "1.28"
+  kcl mod add k8s:1.28
+
+  # Add the module dependency from the GitHub by git url
+  kcl mod add git://github.com/kcl-lang/konfig --tag v0.4.0
+
+  # Add the module dependency from the OCI Registry by oci url
+  kcl mod add oci://ghcr.io/kcl-lang/helloworld --tag 0.1.0
+
+  # Add the module dependency from the local file system by file url
+  kcl mod add /path/to/another_module
+
+  # Add the module dependency from the GitHub by flag
+  kcl mod add --git https://github.com/kcl-lang/konfig --tag v0.4.0
+
+  # Add the module dependency from the OCI Registry by flag
+  kcl mod add --oci https://ghcr.io/kcl-lang/helloworld --tag 0.1.0
+
+  # Add a local dependency by flag
+  kcl mod add --path /path/to/another_module
+
+Flags:
+      --branch string   git repository branch
+      --commit string   git repository commit
+      --git string      git repository url
+  -h, --help            help for add
+      --no_sum_check    do not check the checksum of the package and update kcl.mod.lock
+      --oci string      oci repository url
+      --rename string   rename the dependency
+      --tag string      git or oci repository tag
+
+Global Flags:
+  -q, --quiet   Set the quiet mode (no output)
 ```

docs/tools/cli/package-management/command-reference/3.pkg.md

@@ -31,3 +31,30 @@ Show help for `kcl mod pkm` command.
 ```shell
 kcl mod pkg --target /Users/my_package_tar
 ```
+
+## Reference
+
+```shell
+This command converts a kcl module into tar
+
+Usage:
+  kcl mod pkg [flags]
+
+Examples:
+  # Package the current module
+  kcl mod pkg
+  
+  # Package the current module in the vendor mode
+  kcl mod pkg --vendor
+
+  # Package the current module into the target directory
+  kcl mod pkg --target /path/to/target_dir
+
+Flags:
+  -h, --help            help for pkg
+      --target string   packaged target path
+      --vendor          package in vendor mode (default: false)
+
+Global Flags:
+  -q, --quiet   Set the quiet mode (no output)
+```

docs/tools/cli/package-management/command-reference/4.metadata.md

@@ -39,3 +39,30 @@ Print the metadata of a kcl package and automatically download the missing depen
 ```shell
 kcl mod metadata --update
 ```
+
+## Reference
+
+```shell
+This command outputs the resolved dependencies of a package
+
+Usage:
+  kcl mod metadata [flags]
+
+Examples:
+  # Output the resolved dependencies the current module
+  kcl mod metadata
+  
+  # Output the resolved dependencies the current module in the vendor mode
+  kcl mod metadata --vendor
+
+  # Output the resolved dependencies the current module with the update check
+  kcl mod metadata --update
+
+Flags:
+  -h, --help     help for metadata
+      --update   check the local package and update and download the local package. (default: false)
+      --vendor   run in vendor mode (default: false)
+
+Global Flags:
+  -q, --quiet   Set the quiet mode (no output)
+```

docs/tools/cli/package-management/command-reference/6.login.md

@@ -66,3 +66,31 @@ Username: <account_name>
 Password:
 Login succeeded
 ```
+
+## Reference
+
+```shell
+This command can be used to login to a registry.
+
+Usage:
+  kcl registry login [flags]
+
+Examples:
+  # Login the docker hub
+  kcl registry login docker.io
+
+  # Login the GitHub container registry
+  kcl registry login ghcr.io
+
+  # Login a localhost registry
+  kcl registry login https://localhost:5001
+
+
+Flags:
+  -h, --help              help for login
+  -p, --password string   registry password or identity token
+  -u, --username string   registry username
+
+Global Flags:
+  -q, --quiet   Set the quiet mode (no output)
+```

docs/tools/cli/package-management/command-reference/7.logout.md

@@ -25,3 +25,23 @@ Show help for `kcl registry logout` command.
 ```shell
 kcl registry logout <registry>
 ```
+
+## Reference
+
+```shell
+This command can be used to logout from the current registry.
+
+Usage:
+  kcl registry logout [flags]
+
+Examples:
+  # Logout the registry
+  kcl registry logout docker.io
+
+
+Flags:
+  -h, --help   help for logout
+
+Global Flags:
+  -q, --quiet   Set the quiet mode (no output)
+```

docs/tools/cli/package-management/command-reference/8.push.md

@@ -44,3 +44,27 @@ You can also use `kcl mod push` to upload a tar file to an OCI-based registry.
 ```shell
 kcl mod push --tar_path <tar_path> <oci_url>
 ```
+
+## Reference
+
+```shell
+This command pushes kcl modules to the registry.
+
+Usage:
+  kcl mod push [flags]
+
+Examples:
+  # Push the current module to the registry
+  kcl mod push
+  
+  # Push the current module to the registry in the vendor mode
+  kcl mod push --vendor
+
+Flags:
+  -h, --help              help for push
+      --tar_path string   packaged target path that will be pushed
+      --vendor            run in vendor mode (default: false)
+
+Global Flags:
+  -q, --quiet   Set the quiet mode (no output)
+```

docs/tools/cli/package-management/command-reference/9.pull.md

@@ -40,3 +40,42 @@ You can download a kcl package from an OCI-based registry url.
 ```shell
 kcl mod pull --tag <kcl_package_version> <oci_url>
 ```
+
+## Reference
+
+```shell
+This command pulls kcl modules from the registry.
+
+Usage:
+  kcl mod pull [flags]
+
+Examples:
+  # Pull the the module named "k8s" to the local path from the registry
+  kcl mod pull k8s
+
+  # Pull the module dependency named "k8s" with the version "1.28"
+  kcl mod pull k8s:1.28
+
+  # Pull the module from the GitHub by git url
+  kcl mod pull git://github.com/kcl-lang/konfig --tag v0.4.0
+
+  # Pull the module from the OCI Registry by oci url
+  kcl mod pull oci://ghcr.io/kcl-lang/helloworld --tag 0.1.0
+
+  # Pull the module from the GitHub by flag
+  kcl mod pull --git https://github.com/kcl-lang/konfig --tag v0.4.0
+
+  # Pull the module from the OCI Registry by flag
+  kcl mod pull --oci https://ghcr.io/kcl-lang/helloworld --tag 0.1.0
+
+Flags:
+      --branch string   git repository branch
+      --commit string   git repository commit
+      --git string      git repository url
+  -h, --help            help for pull
+      --oci string      oci repository url
+      --tag string      git or oci repository tag
+
+Global Flags:
+  -q, --quiet   Set the quiet mode (no output)
+```

i18n/zh-CN/docusaurus-plugin-content-docs/current/tools/cli/kcl/docgen.md

@@ -137,6 +137,9 @@ Examples:
   # Generate Markdown document for current package
   kcl doc generate
 
+  # Generate Markdown document for current package and escape the HTML symbols | to \|, \n to <br>, etc.
+  kcl doc generate --escape-html
+
   # Generate Html document for current package
   kcl doc generate --format html