docs: update 0.10.0-alpha API documents

Signed-off-by: peefy <[email protected]>
kcl-lang · Aug 9, 2024 · 3c895c7 · 3c895c7
1 parent e426ace
commit 3c895c7
Show file tree

Hide file tree

Showing 6 changed files with 170 additions and 8 deletions.
diff --git a/docs/reference/xlang-api/kotlin-api.md b/docs/reference/xlang-api/kotlin-api.md
@@ -4,9 +4,35 @@ sidebar_position: 8
 
 # Kotlin API
 
-The official [Kotlin KCL package](https://github.com/kcl-lang/lib/tree/main/kotlin) has not been released yet. Issues and PRs are welcome!
+## Installation
 
-Of course, you can use the KCL Java package to call the KCL API in Kotlin.
+Refer to [this](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry#authenticating-to-github-packages) to configure your Maven; set up your GitHub account and Token in the `settings.xml`.
+
+### Maven
+
+In your project's pom.xml, configure our repository as follows:
+
+```xml
+<repositories>
+    <repository>
+        <id>github</id>
+        <url>https://maven.pkg.github.com/kcl-lang/*</url>
+        <snapshots>
+            <enabled>true</enabled>
+        </snapshots>
+    </repository>
+</repositories>
+```
+
+This way you'll be able to import the above dependency to use the SDK.
+
+```xml
+<dependency>
+    <groupId>com.kcl</groupId>
+    <artifactId>kcl-lib-kotlin</artifactId>
+    <version>0.10.0-alpha.2-SNAPSHOT</version>
+</dependency>
+```
 
 ## Quick Start
 
@@ -18,3 +44,58 @@ val args = execProgramArgs { kFilenameList += "schema.k" }
 val api = API()
 val result = api.execProgram(args)
 ```
+
+## API Reference
+
+### execProgram
+
+Execute KCL file with arguments and return the JSON/YAML result.
+
+<details><summary>Example</summary>
+<p>
+
+The content of `schema.k` is
+
+```python
+schema AppConfig:
+    replicas: int
+
+app: AppConfig {
+    replicas: 2
+}
+```
+
+Kotlin Code
+
+```kotlin
+import com.kcl.api.API
+import com.kcl.api.execProgramArgs
+
+val args = execProgramArgs { kFilenameList += "schema.k" }
+val api = API()
+val result = api.execProgram(args)
+```
+
+</p>
+</details>
+
+### validateCode
+
+Validate code using schema and JSON/YAML data strings.
+
+<details><summary>Example</summary>
+<p>
+
+Kotlin Code
+
+```kotlin
+val args = validateCodeArgs { 
+    code =  "schema Person:\n" + "    name: str\n" + "    age: int\n" + "    check:\n" + "        0 < age < 120\n"
+    data = "{\"name\": \"Alice\", \"age\": 10}"
+}
+val apiInstance = API();
+val result = apiInstance.validateCode(args);
+```
+
+</p>
+</details>
diff --git a/docs/reference/xlang-api/python-api.md b/docs/reference/xlang-api/python-api.md
@@ -174,7 +174,7 @@ assert list(result.symbols.values())[0].ty.schema_name == "AppConfig"
 </p>
 </details>
 
-### list_variable
+### list_variables
 
 list_variables provides users with the ability to parse KCL program and get all variables by specs.
 

diff --git a/.../zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/kotlin-api.md b/.../zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/kotlin-api.md
@@ -4,9 +4,35 @@ sidebar_position: 8
 
 # Kotlin API
 
-[Kotlin KCL API](https://github.com/kcl-lang/lib/tree/main/kotlin) 正在开发当中，尚未正式发布。欢迎提交 Issues 或者 PRs 参与共建!
+## 添加依赖
 
-当然，您也可以在 Kotlin 中直接调用 KCL Java API。
+参考[此处](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry#authenticating-to-github-packages)来配置您的 Maven；在 settings.xml 中设置您的 GitHub 账户和 Token。
+
+### Maven
+
+在您项目的 pom.xml 中，按如下配置 Maven 仓库：
+
+```xml
+<repositories>
+    <repository>
+        <id>github</id>
+        <url>https://maven.pkg.github.com/kcl-lang/*</url>
+        <snapshots>
+            <enabled>true</enabled>
+        </snapshots>
+    </repository>
+</repositories>
+```
+
+通过这种方式，您将能够导入上述依赖以使用 Kotlin SDK。
+
+```xml
+<dependency>
+    <groupId>com.kcl</groupId>
+    <artifactId>kcl-lib-kotlin</artifactId>
+    <version>0.10.0-alpha.2-SNAPSHOT</version>
+</dependency>
+```
 
 ## 快速开始
 
@@ -18,3 +44,58 @@ val args = execProgramArgs { kFilenameList += "schema.k" }
 val api = API()
 val result = api.execProgram(args)
 ```
+
+## API Reference
+
+### execProgram
+
+Execute KCL file with arguments and return the JSON/YAML result.
+
+<details><summary>Example</summary>
+<p>
+
+The content of `schema.k` is
+
+```python
+schema AppConfig:
+    replicas: int
+
+app: AppConfig {
+    replicas: 2
+}
+```
+
+Kotlin Code
+
+```kotlin
+import com.kcl.api.API
+import com.kcl.api.execProgramArgs
+
+val args = execProgramArgs { kFilenameList += "schema.k" }
+val api = API()
+val result = api.execProgram(args)
+```
+
+</p>
+</details>
+
+### validateCode
+
+Validate code using schema and JSON/YAML data strings.
+
+<details><summary>Example</summary>
+<p>
+
+Kotlin Code
+
+```kotlin
+val args = validateCodeArgs { 
+    code =  "schema Person:\n" + "    name: str\n" + "    age: int\n" + "    check:\n" + "        0 < age < 120\n"
+    data = "{\"name\": \"Alice\", \"age\": 10}"
+}
+val apiInstance = API();
+val result = apiInstance.validateCode(args);
+```
+
+</p>
+</details>
diff --git a/.../zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/python-api.md b/.../zh-CN/docusaurus-plugin-content-docs/current/reference/xlang-api/python-api.md
@@ -174,7 +174,7 @@ assert list(result.symbols.values())[0].ty.schema_name == "AppConfig"
 </p>
 </details>
 
-### list_variable
+### list_variables
 
 list_variables provides users with the ability to parse KCL program and get all variables by specs.
 

diff --git a/...CN/docusaurus-plugin-content-docs/version-0.9/reference/xlang-api/python-api.md b/...CN/docusaurus-plugin-content-docs/version-0.9/reference/xlang-api/python-api.md
@@ -174,7 +174,7 @@ assert list(result.symbols.values())[0].ty.schema_name == "AppConfig"
 </p>
 </details>
 
-### list_variable
+### list_variables
 
 list_variables provides users with the ability to parse KCL program and get all variables by specs.
 

diff --git a/versioned_docs/version-0.9/reference/xlang-api/python-api.md b/versioned_docs/version-0.9/reference/xlang-api/python-api.md
@@ -174,7 +174,7 @@ assert list(result.symbols.values())[0].ty.schema_name == "AppConfig"
 </p>
 </details>
 
-### list_variable
+### list_variables
 
 list_variables provides users with the ability to parse KCL program and get all variables by specs.