chore: sync latest version to v0.10 doc and format all documents

Signed-off-by: peefy <[email protected]>

Author: Peefy

blog/2024-09-05-newsletter/index.md

@@ -98,7 +98,7 @@ assert datetime.validate("2024-08-26", "%Y-%m-%d")
 
 - kcl-openapi has been optimized and adjusted for code and document structure.
 - kcl-openapi has added more test cases and optimized the code structure.
-- Package management tools have fixed the bug that compiling multiple *.k files failed.
+- Package management tools have fixed the bug that compiling multiple \*.k files failed.
 - Package management tools supported adding sub-packages in Git repositories as third-party libraries.
 - Package management tools have added some test cases.
 - krm-kcl function fixed some errors in some tests and documents.

docs/reference/lang/codelab/schema.md

@@ -605,6 +605,7 @@ mixin PersistentVolumeClaimMixin for PVCProtocol:
 ```
 
 > Note: for the `k8s.api.core.v1` import to work, we need to initialize a module and add the `k8s` module as a dependency:
+>
 > ```bash
 > kcl mod init
 > kcl mod add k8s

docs/reference/lang/tour.md

@@ -2344,7 +2344,6 @@ Built-in functions and members of schema
 - instances(full_pkg: bool = False)
   Return the list of existing instances of a schema in the main package. When the `full_pkg` is set `True`, return all schema instances in the whole program.
 
-
 ```python
 schema Person:
     name: str

i18n/zh-CN/docusaurus-plugin-content-blog/2024-09-05-newsletter/index.md

@@ -100,7 +100,7 @@ assert datetime.validate("2024-08-26", "%Y-%m-%d")
 
 - kcl-openapi 对代码结构和文档结构进行了优化和调整。
 - kcl-playground 添加了更多的测试用例，对工程结构体进行了优化和升级。
-- 包管理工具修复了编译多个 *.k 文件失败的 bug。
+- 包管理工具修复了编译多个 \*.k 文件失败的 bug。
 - 包管理工具支持添加 Git 仓库中子包作为三方库。
 - 包管理工具新增部分测试用例。
 - krm-kcl function 修复了部分测试和文档中的错误。

i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/lang/spec/schema.md

@@ -816,8 +816,8 @@ Suppose there are schemas a, b, and c, where c inherits b and b inherits a. Sche
 
 Built-in function and members of schema
 
-- instances()
-  Return the list of existing instances of a schema.
+- instances(full_pkg: bool = False)
+  Return the list of existing instances of a schema in the main package. When the `full_pkg` is set `True`, return all schema instances in the whole program.
 
 ### Irrelevant Order Calculation
 

i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/lang/tour.md

@@ -2291,8 +2291,8 @@ schema Person:
 
 内置函数和 schema 成员
 
-- instances（）
-  返回 schema 的现有实例列表。
+- instances(full_pkg: bool = False)
+  返回 schema 的现有实例列表，当 `full_pkg` 设置为 `False` 时，仅返回 main 中的 schema 实例，当 `full_pkg` 设置为 `True` 时，返回整个项目对应 schema 的所有实例。
 
 ```python
 schema Person:

i18n/zh-CN/docusaurus-plugin-content-docs/version-0.10/reference/plugin/overview.md

@@ -173,3 +173,79 @@ import kcl_plugin.my_plugin
 
 result = my_plugin.add(1, 1)
 ```
+
+## 使用 Rust 编写插件
+
+### 0. 先决条件
+
+使用 KCL Rust 插件需要在您的 PATH 中具有 Rust 1.79+，并安装 KCL Rust SDK。
+
+```shell
+cargo add anyhow
+cargo add kclvm-parser --git https://github.com/kcl-lang/kcl
+cargo add kclvm-loader --git https://github.com/kcl-lang/kcl
+cargo add kclvm-evaluator --git https://github.com/kcl-lang/kcl
+cargo add kclvm-runtime --git https://github.com/kcl-lang/kcl
+```
+
+### 1. 你好插件
+
+编写以下 Rust 代码并添加名为 `my_plugin` 的插件。
+
+```rust
+use anyhow::{anyhow, Result};
+use kclvm_evaluator::Evaluator;
+use kclvm_loader::{load_packages, LoadPackageOptions};
+use kclvm_parser::LoadProgramOptions;
+use kclvm_runtime::{Context, IndexMap, PluginFunction, ValueRef};
+use std::{cell::RefCell, rc::Rc, sync::Arc};
+
+fn my_plugin_sum(_: &Context, args: &ValueRef, _: &ValueRef) -> Result<ValueRef> {
+    let a = args
+        .arg_i_int(0, Some(0))
+        .ok_or(anyhow!("expect int value for the first param"))?;
+    let b = args
+        .arg_i_int(1, Some(0))
+        .ok_or(anyhow!("expect int value for the second param"))?;
+    Ok((a + b).into())
+}
+
+fn context_with_plugin() -> Rc<RefCell<Context>> {
+    let mut plugin_functions: IndexMap<String, PluginFunction> = Default::default();
+    let func = Arc::new(my_plugin_sum);
+    plugin_functions.insert("my_plugin.add".to_string(), func);
+    let mut ctx = Context::new();
+    ctx.plugin_functions = plugin_functions;
+    Rc::new(RefCell::new(ctx))
+}
+
+fn main() -> Result<()> {
+    let src = r#"
+import kcl_plugin.my_plugin
+
+sum = my_plugin.add(1, 1)
+"#;
+    let p = load_packages(&LoadPackageOptions {
+        paths: vec!["test.k".to_string()],
+        load_opts: Some(LoadProgramOptions {
+            load_plugins: true,
+            k_code_list: vec![src.to_string()],
+            ..Default::default()
+        }),
+        load_builtin: false,
+        ..Default::default()
+    })?;
+    let evaluator = Evaluator::new_with_runtime_ctx(&p.program, context_with_plugin());
+    let result = evaluator.run()?;
+    println!("yaml result {}", result.1);
+    Ok(())
+}
+```
+
+test.k 的内容为：
+
+```python
+import kcl_plugin.my_plugin
+
+result = my_plugin.add(1, 1)
+```

versioned_docs/version-0.10/reference/lang/codelab/schema.md

@@ -605,6 +605,7 @@ mixin PersistentVolumeClaimMixin for PVCProtocol:
 ```
 
 > Note: for the `k8s.api.core.v1` import to work, we need to initialize a module and add the `k8s` module as a dependency:
+>
 > ```bash
 > kcl mod init
 > kcl mod add k8s

versioned_docs/version-0.10/reference/lang/spec/schema.md

@@ -816,8 +816,8 @@ Suppose there are schemas a, b, and c, where c inherits b and b inherits a. Sche
 
 Built-in function and members of schema
 
-- instances()
-  Return the list of existing instances of a schema.
+- instances(full_pkg: bool = False)
+  Return the list of existing instances of a schema in the main package. When the `full_pkg` is set `True`, return all schema instances in the whole program.
 
 ### Irrelevant Order Calculation
 

versioned_docs/version-0.10/reference/lang/tour.md

@@ -2341,8 +2341,8 @@ Note that the current version of KCL does not yet support user-defined decorator
 
 Built-in functions and members of schema
 
-- instances()
-  Return the list of existing instances of a schema.
+- instances(full_pkg: bool = False)
+  Return the list of existing instances of a schema in the main package. When the `full_pkg` is set `True`, return all schema instances in the whole program.
 
 ```python
 schema Person:

versioned_docs/version-0.10/reference/plugin/overview.md

@@ -174,3 +174,79 @@ import kcl_plugin.my_plugin
 
 result = my_plugin.add(1, 1)
 ```
+
+## Use Rust to Write Plugins
+
+### 0. Prerequisites
+
+Using the KCL Rust plugin requires the presence of `Rust 1.79+` in your `PATH` and install the KCL Rust SDK.
+
+```shell
+cargo add anyhow
+cargo add kclvm-parser --git https://github.com/kcl-lang/kcl
+cargo add kclvm-loader --git https://github.com/kcl-lang/kcl
+cargo add kclvm-evaluator --git https://github.com/kcl-lang/kcl
+cargo add kclvm-runtime --git https://github.com/kcl-lang/kcl
+```
+
+### 1. Hello Plugin
+
+Write the following Rust code and add the the plugin named `my_plugin`.
+
+```rust
+use anyhow::{anyhow, Result};
+use kclvm_evaluator::Evaluator;
+use kclvm_loader::{load_packages, LoadPackageOptions};
+use kclvm_parser::LoadProgramOptions;
+use kclvm_runtime::{Context, IndexMap, PluginFunction, ValueRef};
+use std::{cell::RefCell, rc::Rc, sync::Arc};
+
+fn my_plugin_sum(_: &Context, args: &ValueRef, _: &ValueRef) -> Result<ValueRef> {
+    let a = args
+        .arg_i_int(0, Some(0))
+        .ok_or(anyhow!("expect int value for the first param"))?;
+    let b = args
+        .arg_i_int(1, Some(0))
+        .ok_or(anyhow!("expect int value for the second param"))?;
+    Ok((a + b).into())
+}
+
+fn context_with_plugin() -> Rc<RefCell<Context>> {
+    let mut plugin_functions: IndexMap<String, PluginFunction> = Default::default();
+    let func = Arc::new(my_plugin_sum);
+    plugin_functions.insert("my_plugin.add".to_string(), func);
+    let mut ctx = Context::new();
+    ctx.plugin_functions = plugin_functions;
+    Rc::new(RefCell::new(ctx))
+}
+
+fn main() -> Result<()> {
+    let src = r#"
+import kcl_plugin.my_plugin
+
+sum = my_plugin.add(1, 1)
+"#;
+    let p = load_packages(&LoadPackageOptions {
+        paths: vec!["test.k".to_string()],
+        load_opts: Some(LoadProgramOptions {
+            load_plugins: true,
+            k_code_list: vec![src.to_string()],
+            ..Default::default()
+        }),
+        load_builtin: false,
+        ..Default::default()
+    })?;
+    let evaluator = Evaluator::new_with_runtime_ctx(&p.program, context_with_plugin());
+    let result = evaluator.run()?;
+    println!("yaml result {}", result.1);
+    Ok(())
+}
+```
+
+The content of `test.k` are:
+
+```python
+import kcl_plugin.my_plugin
+
+result = my_plugin.add(1, 1)
+```