Merge pull request #337 from Peefy/update-kcl-cli-documents

docs: update kcl cli documents

Author: Peefy

blog/2024-04-17-newsletter/index.md

@@ -66,7 +66,7 @@ cargo add --git https://github.com/kcl-lang/lib
 
 - The initial release of the KCL Node.js SDK. Repository link: [https://github.com/kcl-lang/lib/tree/main/nodejs](https://github.com/kcl-lang/lib/tree/main/nodejs). Contributions are welcome.
 
-+ `__test__/test_data/schema.k`
+* `__test__/test_data/schema.k`
 
 ```python
 schema AppConfig:
@@ -77,39 +77,43 @@ app: AppConfig {
 }
 ```
 
-+ `execProgram`
+- `execProgram`
 
 ```ts
 import { execProgram, ExecProgramArgs } from "kcl-lib";
 
 function main() {
   const result = execProgram(ExecProgramArgs(["__test__/test_data/schema.k"]));
-  console.log(result.yamlResult);  // 'app:\n  replicas: 2'
+  console.log(result.yamlResult); // 'app:\n  replicas: 2'
 }
 
 main();
 ```
 
-+ `listVariables`
+- `listVariables`
 
 ```ts
 import { listVariables, ListVariablesArgs } from "kcl-lib";
 
 function main() {
-  const result = listVariables(ListVariablesArgs('__test__/test_data/schema.k', []))
-  console.log(result.variables['app'].value);  // 'AppConfig {replicas: 2}'
+  const result = listVariables(
+    ListVariablesArgs("__test__/test_data/schema.k", []),
+  );
+  console.log(result.variables["app"].value); // 'AppConfig {replicas: 2}'
 }
 
 main();
 ```
 
-+ `loadPackage`
+- `loadPackage`
 
 ```ts
 import { loadPackage, LoadPackageArgs } from "kcl-lib";
 
 function main() {
-  const result = loadPackage(LoadPackageArgs(['__test__/test_data/schema.k'], [], true));
+  const result = loadPackage(
+    LoadPackageArgs(["__test__/test_data/schema.k"], [], true),
+  );
   console.log(result.symbols);
 }
 

docs/tools/cli/kcl/docgen.md

@@ -95,7 +95,7 @@ Refer to [reST](https://docutils.sourceforge.io/rst.html) for more information.
 ### kcl doc
 
 ```shell
-This command shows documentation for KCL package or symbol.
+This command shows documentation for KCL modules or symbols.
 
 Usage:
   kcl doc [command]
@@ -107,7 +107,6 @@ Examples:
   # Generate document for current package
   kcl doc generate
 
-
 Available Commands:
   generate    Generates documents from code and examples
 
@@ -120,6 +119,8 @@ Use "kcl doc [command] --help" for more information about a command.
 ### kcl doc generate
 
 ```shell
+This command generates documents for KCL modules.
+
 Usage:
   kcl doc generate [flags]
 
@@ -139,7 +140,6 @@ Examples:
   # Generate Markdown document for specific package to a <target directory>
   kcl doc generate --file-path <package path> --target <target directory>
 
-
 Flags:
       --escape-html         Whether to escape html symbols when the output format is markdown. Always scape when the output format is html. Default to false.
       --file-path string    Relative or absolute path to the KCL package root when running kcl-doc command from

docs/tools/cli/kcl/lint.md

@@ -53,14 +53,13 @@ Examples:
   kcl lint path/to/kcl1.k path/to/kcl2.k
 
   # Lint OCI packages
-  kcl lint oci://ghcr.io/kcl-lang/hello-world
+  kcl lint oci://ghcr.io/kcl-lang/helloworld
 
   # Lint the current package
   kcl lint
 
-
 Flags:
-  -D, --argument strings        Specify the top-level argument
+  -D, --argument stringArray    Specify the top-level argument
   -d, --debug                   Run in debug mode
   -n, --disable_none            Disable dumping None values
   -E, --external strings        Specify the mapping of package name and path where the package is located
@@ -72,6 +71,7 @@ Flags:
   -S, --path_selector strings   Specify the path selectors
   -q, --quiet                   Set the quiet mode (no output)
   -Y, --setting strings         Specify the command line setting files
+  -H, --show_hidden             Display hidden attributes
   -k, --sort_keys               Sort output result keys
   -r, --strict_range_check      Do perform strict numeric range checks
   -t, --tag string              Specify the tag for the OCI or Git artifact

docs/tools/cli/kcl/overview.md

@@ -27,6 +27,12 @@ KCL toolchain is a toolset of KCL language, which aims to improve the efficiency
 ## Args
 
 ```shell
+The KCL Command Line Interface (CLI).
+
+KCL is an open-source, constraint-based record and functional language that
+enhances the writing of complex configurations, including those for cloud-native
+scenarios. The KCL website: https://kcl-lang.io
+
 Usage:
   kcl [command]
 
@@ -35,8 +41,9 @@ Available Commands:
   completion  Generate the autocompletion script for the specified shell
   doc         KCL document tool
   fmt         KCL format tool
+  help        Help about any command
   import      KCL import tool
-  lint        Run KCL codes.
+  lint        Lint KCL codes.
   mod         KCL module management
   play        Open the kcl playground in the browser.
   registry    KCL registry management
@@ -50,8 +57,5 @@ Flags:
   -h, --help      help for kcl
   -v, --version   version for kcl
 
-Additional help topics:
-  kcl
-
 Use "kcl [command] --help" for more information about a command.
 ```

docs/tools/cli/kcl/run.md

@@ -9,6 +9,10 @@ This command runs the kcl code and displays the output. 'kcl run' takes multiple
 ## Args
 
 ```shell
+This command runs the kcl code and displays the output. 'kcl run' takes multiple input for arguments.
+
+For example, 'kcl run path/to/kcl.k' will run the file named path/to/kcl.k
+
 Usage:
   kcl run [flags]
 
@@ -26,14 +30,16 @@ Examples:
   kcl run path/to/kcl1.k path/to/kcl2.k
 
   # Run OCI packages
-  kcl run oci://ghcr.io/kcl-lang/hello-world
+  kcl run oci://ghcr.io/kcl-lang/helloworld
+
+  # Run remote Git repo
+  kcl run https://github.com/kcl-lang/flask-demo-kcl-manifests
 
   # Run the current package
   kcl run
 
-
 Flags:
-  -D, --argument strings        Specify the top-level argument
+  -D, --argument stringArray    Specify the top-level argument
   -d, --debug                   Run in debug mode
   -n, --disable_none            Disable dumping None values
   -E, --external strings        Specify the mapping of package name and path where the package is located
@@ -45,6 +51,7 @@ Flags:
   -S, --path_selector strings   Specify the path selectors
   -q, --quiet                   Set the quiet mode (no output)
   -Y, --setting strings         Specify the command line setting files
+  -H, --show_hidden             Display hidden attributes
   -k, --sort_keys               Sort output result keys
   -r, --strict_range_check      Do perform strict numeric range checks
   -t, --tag string              Specify the tag for the OCI or Git artifact

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

@@ -0,0 +1,27 @@
+# kcl mod graph
+
+Print the module dependency graph. Each module is identified as a string of the form path@version.
+
+## Usage
+
+```shell
+kcl mod graph [flags]
+```
+
+## Description
+
+`kcl mod graph` will print the module dependency graph. Each module is identified as a string of the form path@version.
+
+## Options
+
+### --help, -h
+
+Show help for `kcl mod graph` command.
+
+## Examples
+
+### Print the current module dependency graph.
+
+```shell
+kcl mod graph
+```

docs/user_docs/support/faq-kcl.md

@@ -2539,34 +2539,34 @@ The above KCL code gives the output:
 
 ```yaml
 final_list:
-- 1
-- 2
-- 3
-- 4
-- 5
-- 6
+  - 1
+  - 2
+  - 3
+  - 4
+  - 5
+  - 6
 ```
 
 ## 61. What does `version: "v1" = "v1"` mean?
 
 The first `"v1"` over here denotes that the type of the variable `version` is of string literal type. The second `"v1"` denotes that the default value of the variable `version` is `"v1"`.
 
-## 62. How do i define a schema to verify the contents of a given JSON file?
+## 62. How to define a schema to verify the contents of a given JSON file?
 
-We can use the kcl `vet` tool to validate the JSON data in a given JSOn file. For example, in the below data.json file we use the KCL file(schema.k) below to validate the `age` parameter. 
+We can use the kcl `vet` tool to validate the JSON data in a given JSOn file. For example, in the below data.json file we use the KCL file(schema.k) below to validate the `age` parameter.
 
 data.json
 
 ```json
 [
-    {
-        "name": "Alice",
-        "age": 18
-    },
-    {
-        "name": "Bob",
-        "age": 10
-    }
+  {
+    "name": "Alice",
+    "age": 18
+  },
+  {
+    "name": "Bob",
+    "age": 10
+  }
 ]
 ```
 
@@ -2583,7 +2583,6 @@ schema Person:
 
 The command to validate the JSON data below gives the output `Validate success!`.
 
-```bash 
+```bash
 kcl vet data.json schema.k
 ```
-

i18n/zh-CN/docusaurus-plugin-content-blog/2024-04-17-newsletter/index.md

@@ -66,7 +66,7 @@ cargo add --git https://github.com/kcl-lang/lib
 
 - KCL Node.js SDK 初版发布，仓库地址 [https://github.com/kcl-lang/lib/tree/main/nodejs](https://github.com/kcl-lang/lib/tree/main/nodejs), 欢迎共建
 
-+ `__test__/test_data/schema.k`
+* `__test__/test_data/schema.k`
 
 ```python
 schema AppConfig:
@@ -77,39 +77,43 @@ app: AppConfig {
 }
 ```
 
-+ `execProgram`
+- `execProgram`
 
 ```ts
 import { execProgram, ExecProgramArgs } from "kcl-lib";
 
 function main() {
   const result = execProgram(ExecProgramArgs(["__test__/test_data/schema.k"]));
-  console.log(result.yamlResult);  // 'app:\n  replicas: 2'
+  console.log(result.yamlResult); // 'app:\n  replicas: 2'
 }
 
 main();
 ```
 
-+ `listVariables`
+- `listVariables`
 
 ```ts
 import { listVariables, ListVariablesArgs } from "kcl-lib";
 
 function main() {
-  const result = listVariables(ListVariablesArgs('__test__/test_data/schema.k', []))
-  console.log(result.variables['app'].value);  // 'AppConfig {replicas: 2}'
+  const result = listVariables(
+    ListVariablesArgs("__test__/test_data/schema.k", []),
+  );
+  console.log(result.variables["app"].value); // 'AppConfig {replicas: 2}'
 }
 
 main();
 ```
 
-+ `loadPackage`
+- `loadPackage`
 
 ```ts
 import { loadPackage, LoadPackageArgs } from "kcl-lib";
 
 function main() {
-  const result = loadPackage(LoadPackageArgs(['__test__/test_data/schema.k'], [], true));
+  const result = loadPackage(
+    LoadPackageArgs(["__test__/test_data/schema.k"], [], true),
+  );
   console.log(result.symbols);
 }
 

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

@@ -95,7 +95,7 @@ kcl doc generate --file-path <package path> --target <target directory>
 ### kcl doc
 
 ```shell
-This command shows documentation for KCL package or symbol.
+This command shows documentation for KCL modules or symbols.
 
 Usage:
   kcl doc [command]
@@ -107,7 +107,6 @@ Examples:
   # Generate document for current package
   kcl doc generate
 
-
 Available Commands:
   generate    Generates documents from code and examples
 
@@ -120,6 +119,8 @@ Use "kcl doc [command] --help" for more information about a command.
 ### kcl doc generate
 
 ```shell
+This command generates documents for KCL modules.
+
 Usage:
   kcl doc generate [flags]
 
@@ -139,7 +140,6 @@ Examples:
   # Generate Markdown document for specific package to a <target directory>
   kcl doc generate --file-path <package path> --target <target directory>
 
-
 Flags:
       --escape-html         Whether to escape html symbols when the output format is markdown. Always scape when the output format is html. Default to false.
       --file-path string    Relative or absolute path to the KCL package root when running kcl-doc command from

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

@@ -53,14 +53,13 @@ Examples:
   kcl lint path/to/kcl1.k path/to/kcl2.k
 
   # Lint OCI packages
-  kcl lint oci://ghcr.io/kcl-lang/hello-world
+  kcl lint oci://ghcr.io/kcl-lang/helloworld
 
   # Lint the current package
   kcl lint
 
-
 Flags:
-  -D, --argument strings        Specify the top-level argument
+  -D, --argument stringArray    Specify the top-level argument
   -d, --debug                   Run in debug mode
   -n, --disable_none            Disable dumping None values
   -E, --external strings        Specify the mapping of package name and path where the package is located
@@ -72,6 +71,7 @@ Flags:
   -S, --path_selector strings   Specify the path selectors
   -q, --quiet                   Set the quiet mode (no output)
   -Y, --setting strings         Specify the command line setting files
+  -H, --show_hidden             Display hidden attributes
   -k, --sort_keys               Sort output result keys
   -r, --strict_range_check      Do perform strict numeric range checks
   -t, --tag string              Specify the tag for the OCI or Git artifact