Add Introduction, Getting Started, and Features docs

8 files changed, 686 insertions, 0 deletions

diff --git a/docs/_sidebar.md b/docs/_sidebar.md
index e910178..d60a631 100644
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -1,3 +1,6 @@
 - [Welcome!](README)
+* [Introduction](pages/1-intro)
+* [Getting Started](pages/2-getting-started)
 * Other
+  * [Features](pages/other/features)
   * [Naming Conventions](pages/other/naming_rule)
diff --git a/docs/_zh_CN/_sidebar.md b/docs/_zh_CN/_sidebar.md
index 20615d5..1fd2e13 100644
--- a/docs/_zh_CN/_sidebar.md
+++ b/docs/_zh_CN/_sidebar.md
@@ -1,3 +1,6 @@
 - [Welcome!](README)
+* [介绍](pages/1-intro)
+* [起步](pages/2-getting-started)
 * 其他
+  * [特性](pages/other/features)
   * [命名规范](pages/other/naming_rule)
diff --git a/docs/_zh_CN/pages/1-intro.md b/docs/_zh_CN/pages/1-intro.md
new file mode 100644
index 0000000..7210d2e
--- /dev/null
+++ b/docs/_zh_CN/pages/1-intro.md
@@ -0,0 +1,32 @@
+<h1 align="center">介绍</h1>
+
+如果你正被这些问题困扰——
+
+1. 子命令一多，`main.rs` 就迅速膨胀；
+2. Handler 中的逻辑与副作用混杂在一起；
+3. 日志、鉴权等横切关注点难以无侵入地插入；
+4. 为多个平台维护 shell 补全脚本令人心力交瘁；
+5. 全局资源到处都是，测试非常困难。
+
+…… 那么，你来对地方了。
+
+当然，如果只是对「怎么用 Rust 写出好维护的 CLI」这件事感兴趣，那你更来对地方了 —— 它会很有意思的。
+
+## 什么是 Mingling？
+
+> **Mìng Lìng** 是中文 **命令** 的汉语拼音，
+> 对应的英文单词是 **Command**。
+
+Mingling 是一个用 Rust 构建的 CLI 框架。它免费、开源，且使用宽松的 MIT / Apache 2.0 开源协议。
+
+Mingling 的设计目标：
+
+- **可扩展**：从 3 个子命令到 30 个，同一套模式，不换框架
+- **解耦**：参数解析写一次，业务逻辑写一次，输出格式写一次。各不相干
+- **类型驱动**：整个流水线上传递的是清晰、类型化的数据，而非 `Vec<String>`
+- **轻量依赖**：核心功能依赖少，引入负担低；按需启用高级特性，不拖慢编译
+- **高效**：编译期生成分发逻辑，运行时没有不必要的开销
+
+---
+
+好了，想来试试么？
diff --git a/docs/_zh_CN/pages/2-getting-started.md b/docs/_zh_CN/pages/2-getting-started.md
new file mode 100644
index 0000000..57b32e4
--- /dev/null
+++ b/docs/_zh_CN/pages/2-getting-started.md
@@ -0,0 +1,62 @@
+<h1 align="center">起步</h1>
+
+## 创建一个新项目
+
+```bash
+cargo new my-cli
+cd my-cli
+```
+
+## 添加依赖
+
+在 `Cargo.toml` 写入如下内容
+
+```toml
+[dependencies.mingling]
+version = "0.2"
+features = []
+```
+
+## 启用特性
+
+**Mingling** 默认所有特性关闭，且不提供类似 `full` 的全开特性。
+
+因为部分特性会 **直接影响整个生命周期的行为**，需要你按需启用，例如：
+
+```toml
+[dependencies.mingling]
+version = "0.2"
+features = [
+    "parser",
+    "comp",
+]
+```
+
+> [!NOTE]
+> 请前往 [docs.rs](https://docs.rs/mingling/latest/mingling/feature/index.html) 或 [特性](pages/other/features) 以了解所有特性
+
+## 编写基本入口
+
+编写 `src/main.rs`，写入以下代码：
+
+```rust
+use mingling::prelude::*;
+
+fn main() {
+    let mut program = ThisProgram::new();
+    
+    program.exec_and_exit();
+}
+
+gen_program!();
+```
+
+## 编译验证
+
+```plaintext
+~# cargo check
+```
+
+---
+
+一切无误后，开始写点什么吧！
diff --git a/docs/_zh_CN/pages/other/features.md b/docs/_zh_CN/pages/other/features.md
new file mode 100644
index 0000000..b04f1b8
--- /dev/null
+++ b/docs/_zh_CN/pages/other/features.md
@@ -0,0 +1,246 @@
+<h1 align="center">特性</h1>
+<p align="center">
+    <b>Mingling</b> 的所有特性一览
+</p>
+
+## 特性 `all_serde_fmt`
+
+**介绍:**
+
+为 `general_renderer` 启用所有序列化格式（JSON、RON、TOML、YAML）的 serde 格式化支持。
+
+开启此特性将自动启用 `json_serde_fmt`、`ron_serde_fmt`、`toml_serde_fmt`、`yaml_serde_fmt` 四个子特性。
+
+## 特性 `async`
+
+**介绍:**
+
+启用异步运行时支持，允许 `#[chain]` 绑定 `async` 函数，例如：
+
+```rust
+// Features: ["async"]
+
+pack!(StateFoo = ());
+
+#[chain]
+async fn handle_state_foo(foo: StateFoo) -> Next {
+    StateFoo::new(())
+} 
+```
+
+详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-async-support)
+
+## 特性 `builds`
+
+**介绍:**
+
+启用部分需要在 `build.rs` 使用的脚本，目前包含：
+
+1. `comp` 特性下的补全脚本生成：
+
+```rust
+// Features: ["builds", "comp"]
+use mingling::build::build_comp_scripts;
+
+fn main() {
+    // 为 `myprogram` 生成补全脚本
+    build_comp_scripts("myprogram").unwrap();
+}
+```
+
+## 特性 `clap`
+
+**介绍:**
+
+启用与 [clap](https://crates.io/crates/clap) 命令行参数解析库的集成，方便构建 CLI 应用程序。
+
+开启此特性后，可以使用 `#[dispatcher_clap]` 属性宏从 `clap::Parser` 结构体生成 dispatcher。
+
+详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-clap-binding)
+
+## 特性 `comp`
+
+**介绍:**
+
+启用代码补全功能，为交互式环境提供自动补全支持。
+
+开启后可以使用 `#[completion]` 属性宏定义动态补全逻辑，并支持为 bash、zsh、fish、pwsh 等 shell 生成补全脚本。
+
+详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-completion)
+
+## 特性 `debug`
+
+**介绍:**
+
+启用调试相关功能，提供更详细的错误信息和诊断输出。
+
+## 特性 `dispatch_tree`
+
+**介绍:**
+
+启用调度树机制，支持基于条件的分发和路由功能。
+
+开启后，Mingling 在**编译时**将子命令结构硬编码为前缀树（Trie），实现极速的子命令查找。查找复杂度为 **O(n)**，其中 _n_ 是输入长度，而非命令数量。
+
+详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-dispatch-tree)
+
+## 特性 `extra_macros`
+
+**介绍:**
+
+启用额外的宏集合，提供更多便捷的语法糖和元编程能力。
+
+例如，允许 `dispatcher!("greet")` 的缩写形式，自动生成 `CMDGreet` / `EntryGreet`。
+
+| 宏 | 说明 |
+|---|---|
+| `empty_result!()` | 链中提前返回空结果的简写 |
+| `entry!(Type, ["a", "b"])` | 构造入口类型的测试数据 |
+| `#[program_setup]` | 声明程序初始化函数 |
+| `dispatcher!("cmd.path")` **缩写形式** | 省略 `CMDStruct => EntryStruct`，名字自动推导 |
+
+<details>
+<summary> Details </summary>
+
+### `empty_result!()`
+
+```rust
+// Features: ["extra_macros"]
+
+pack!(StatePrev1 = ());
+pack!(StatePrev2 = ());
+
+pack!(StateNext = ());
+
+#[chain]
+fn handle_state_prev2(_p: StatePrev1) {
+    // 无 Next 的 #[chain] 可以直接不返回值
+}
+
+#[chain]
+fn handle_state_prev1(_p: StatePrev1) -> Next {
+    let foo = 1;
+    let bar = 2;
+    if foo != bar {
+        // 当需要 Next 且不需要返回值，便可以使用它
+        empty_result!()
+    } else {
+        StateNext::new(()).into()
+    }
+}
+```
+
+### `#[program_setup]`
+
+```rust
+// Features: ["extra_macros"]
+use mingling::{macros::program_setup, Program};
+
+fn main() {
+    let mut program = ThisProgram::new();
+    program.with_setup(NoErrorSetup);
+    program.exec_and_exit();
+}
+
+#[program_setup]
+fn no_error_setup(program: &mut Program<ThisProgram>) {
+    program.global_flag(["--no-error"], |program| {
+        program.stdout_setting.error_output = false;
+    });
+}
+```
+
+### `entry!`
+
+```rust
+// Features: ["extra_macros"]
+use mingling::macros::entry;
+
+pack!(EntryHello = Vec<String>);
+
+fn main() {
+    let result = handle_hello(entry!("--name", "Bob")).into();
+    // ... 此处为断言逻辑
+}
+
+#[chain]
+fn handle_hello(args: EntryHello) {}
+```
+
+</details>
+
+## 特性 `general_renderer`
+
+**介绍:**
+
+启用通用渲染器，提供基础的内容渲染能力。开启此特性将自动启用 `json_serde_fmt`。
+
+开启后，用户可以通过 `--json` 或 `--yaml` 等标志获取结构化输出。
+
+详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-general-renderer)
+
+## 特性 `general_renderer_empty`
+
+**介绍:**
+
+启用通用渲染器的空实现版本，适用于不需要实际渲染功能的场景。此特性不启用任何 serde 格式化后端。
+
+## 特性 `general_renderer_full`
+
+**介绍:**
+
+启用通用渲染器的完整实现，包含所有渲染功能和序列化格式支持。开启此特性将自动启用 `all_serde_fmt`。
+
+## 特性 `json_serde_fmt`
+
+**介绍:**
+
+启用 JSON 格式的 serde 序列化/反序列化格式化支持。
+
+## 特性 `nightly`
+
+**介绍:**
+
+启用仅在不稳定（Nightly）Rust 编译器中可用的实验性功能。
+
+## 特性 `parser`
+
+**介绍:**
+
+启用解析器模块，提供文本解析和语法分析功能。
+
+开启后可以使用 `Picker` 进行零成本的参数提取，支持 `pick()` 和 `pick_or()` 等方法。
+
+详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-argument-parse)
+
+## 特性 `repl`
+
+**介绍:**
+
+启用交互式 REPL（Read-Eval-Print Loop）环境支持。
+
+开启后，可以通过 `program.exec_repl()` 将 CLI 转变为交互式 shell。
+
+详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-repl-basic)
+
+## 特性 `ron_serde_fmt`
+
+**介绍:**
+
+启用 RON（Rusty Object Notation）格式的 serde 序列化/反序列化格式化支持。
+
+## 特性 `toml_serde_fmt`
+
+**介绍:**
+
+启用 TOML 格式的 serde 序列化/反序列化格式化支持。
+
+## 特性 `yaml_serde_fmt`
+
+**介绍:**
+
+启用 YAML 格式的 serde 序列化/反序列化格式化支持。
+
+<p align="center" style="font-size: 0.85em; color: gray;">
+    Written by @Weicao-CatilGrass
+</p>
diff --git a/docs/pages/1-intro.md b/docs/pages/1-intro.md
new file mode 100644
index 0000000..edf83bb
--- /dev/null
+++ b/docs/pages/1-intro.md
@@ -0,0 +1,32 @@
+<h1 align="center">Introduction</h1>
+
+If you're troubled by these issues —
+
+1. Too many subcommands make `main.rs` bloat rapidly;
+2. Handler logic mixed with side effects;
+3. Logging, auth, and other cross-cutting concerns are hard to inject non-invasively;
+4. Maintaining shell completion scripts for multiple platforms wears you out;
+5. Global resources everywhere, making testing difficult.
+
+… then you've come to the right place.
+
+Of course, if you're just curious about "how to write maintainable CLIs in Rust," you've also come to the right place — it'll be fun.
+
+## What is Mingling?
+
+> **Mìng Lìng** is the pinyin of the Chinese word **命令**,
+> which translates to **Command** in English.
+
+Mingling is a CLI framework built with Rust. It's free, open-source, and licensed under the permissive MIT / Apache 2.0 license.
+
+Mingling's design goals:
+
+- **Extensible**: From 3 subcommands to 30, same pattern, no framework swap
+- **Decoupled**: Parse args once, write business logic once, define output format once. Each independent.
+- **Type-driven**: Clear, typed data flows through the pipeline — not `Vec<String>`
+- **Lightweight deps**: Minimal core deps, low cost to pull in; advanced features on demand, no compile-time drag
+- **Efficient**: Dispatch logic generated at compile time, no unnecessary runtime overhead
+
+---
+
+Alright, wanna give it a try?
diff --git a/docs/pages/2-getting-started.md b/docs/pages/2-getting-started.md
new file mode 100644
index 0000000..77503e9
--- /dev/null
+++ b/docs/pages/2-getting-started.md
@@ -0,0 +1,62 @@
+<h1 align="center">Getting Started</h1>
+
+## Create a New Project
+
+```bash
+cargo new my-cli
+cd my-cli
+```
+
+## Add Dependency
+
+Add the following to `Cargo.toml`:
+
+```toml
+[dependencies.mingling]
+version = "0.2"
+features = []
+```
+
+## Enable Features
+
+**Mingling** has all features disabled by default and does not provide an all-in-one feature like `full`.
+
+Some features will **directly affect the behavior of the entire lifecycle**, so you need to enable them as needed, for example:
+
+```toml
+[dependencies.mingling]
+version = "0.2"
+features = [
+    "parser",
+    "comp",
+]
+```
+
+> [!NOTE]
+> Visit [docs.rs](https://docs.rs/mingling/latest/mingling/feature/index.html) or [Features](pages/other/features) to learn about all available features.
+
+## Write the Basic Entry Point
+
+Edit `src/main.rs` with the following code:
+
+```rust
+use mingling::prelude::*;
+
+fn main() {
+    let mut program = ThisProgram::new();
+
+    program.exec_and_exit();
+}
+
+gen_program!();
+```
+
+## Verify Compilation
+
+```plaintext
+~# cargo check
+```
+
+---
+
+Once everything is good, start building!
diff --git a/docs/pages/other/features.md b/docs/pages/other/features.md
new file mode 100644
index 0000000..8f458af
--- /dev/null
+++ b/docs/pages/other/features.md
@@ -0,0 +1,246 @@
+<h1 align="center">Features</h1>
+<p align="center">
+    <b>Mingling</b>'s complete feature list
+</p>
+
+## Feature `all_serde_fmt`
+
+**Description:**
+
+Enables serde formatting support for all serialization formats (JSON, RON, TOML, YAML) in `general_renderer`.
+
+Enabling this feature will automatically enable the four sub-features: `json_serde_fmt`, `ron_serde_fmt`, `toml_serde_fmt`, `yaml_serde_fmt`.
+
+## Feature `async`
+
+**Description:**
+
+Enables async runtime support, allowing `#[chain]` to bind `async` functions, e.g.:
+
+```rust
+// Features: ["async"]
+
+pack!(StateFoo = ());
+
+#[chain]
+async fn handle_state_foo(foo: StateFoo) -> Next {
+    StateFoo::new(())
+} 
+```
+
+See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-async-support)
+
+## Feature `builds`
+
+**Description:**
+
+Enables scripts needed for use in `build.rs`, currently including:
+
+1. Completion script generation under the `comp` feature:
+
+```rust
+// Features: ["builds", "comp"]
+use mingling::build::build_comp_scripts;
+
+fn main() {
+    // Generate completion scripts for `myprogram`
+    build_comp_scripts("myprogram").unwrap();
+}
+```
+
+## Feature `clap`
+
+**Description:**
+
+Enables integration with the [clap](https://crates.io/crates/clap) command-line argument parsing library, making it easy to build CLI apps.
+
+With this feature enabled, you can use the `#[dispatcher_clap]` attribute macro to generate a dispatcher from a `clap::Parser` struct.
+
+See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-clap-binding)
+
+## Feature `comp`
+
+**Description:**
+
+Enables code completion functionality, providing auto-completion support for interactive environments.
+
+When enabled, you can use the `#[completion]` attribute macro to define dynamic completion logic, and generate completion scripts for shells such as bash, zsh, fish, and pwsh.
+
+See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-completion)
+
+## Feature `debug`
+
+**Description:**
+
+Enables debugging-related features, providing more detailed error info and diagnostic output.
+
+## Feature `dispatch_tree`
+
+**Description:**
+
+Enables the dispatch tree mechanism, supporting conditional dispatch and routing.
+
+When enabled, Mingling **at compile time** hard-codes the subcommand structure as a prefix tree (Trie), achieving extremely fast subcommand lookup. Lookup complexity is **O(n)**, where _n_ is the input length, not the number of commands.
+
+See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-dispatch-tree)
+
+## Feature `extra_macros`
+
+**Description:**
+
+Enables an additional set of macros, providing more convenient syntactic sugar and metaprogramming capabilities.
+
+For example, allows the shorthand form `dispatcher!("greet")`, which auto-generates `CMDGreet` / `EntryGreet`.
+
+| Macro | Description |
+|---|---|
+| `empty_result!()` | Shorthand for returning an empty result early in a chain |
+| `entry!(Type, ["a", "b"])` | Construct test data for an entry type |
+| `#[program_setup]` | Declare a program initialization function |
+| `dispatcher!("cmd.path")` **shorthand** | Omit `CMDStruct => EntryStruct`, names are auto-derived |
+
+<details>
+<summary> Details </summary>
+
+### `empty_result!()`
+
+```rust
+// Features: ["extra_macros"]
+
+pack!(StatePrev1 = ());
+pack!(StatePrev2 = ());
+
+pack!(StateNext = ());
+
+#[chain]
+fn handle_state_prev2(_p: StatePrev1) {
+    // A #[chain] with no return type can simply omit the return value
+}
+
+#[chain]
+fn handle_state_prev1(_p: StatePrev1) -> Next {
+    let foo = 1;
+    let bar = 2;
+    if foo != bar {
+        // When Next is needed but no return value is required, use this
+        empty_result!()
+    } else {
+        StateNext::new(()).into()
+    }
+}
+```
+
+### `#[program_setup]`
+
+```rust
+// Features: ["extra_macros"]
+use mingling::{macros::program_setup, Program};
+
+fn main() {
+    let mut program = ThisProgram::new();
+    program.with_setup(NoErrorSetup);
+    program.exec_and_exit();
+}
+
+#[program_setup]
+fn no_error_setup(program: &mut Program<ThisProgram>) {
+    program.global_flag(["--no-error"], |program| {
+        program.stdout_setting.error_output = false;
+    });
+}
+```
+
+### `entry!`
+
+```rust
+// Features: ["extra_macros"]
+use mingling::macros::entry;
+
+pack!(EntryHello = Vec<String>);
+
+fn main() {
+    let result = handle_hello(entry!("--name", "Bob")).into();
+    // ... assertion logic here
+}
+
+#[chain]
+fn handle_hello(args: EntryHello) {}
+```
+
+</details>
+
+## Feature `general_renderer`
+
+**Description:**
+
+Enables the general renderer, providing basic content rendering capabilities. Enabling this feature will automatically enable `json_serde_fmt`.
+
+When enabled, users can get structured output via flags like `--json` or `--yaml`.
+
+See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-general-renderer)
+
+## Feature `general_renderer_empty`
+
+**Description:**
+
+Enables an empty implementation of the general renderer, suitable for scenarios where no actual rendering is needed. This feature does not enable any serde formatting backend.
+
+## Feature `general_renderer_full`
+
+**Description:**
+
+Enables the full implementation of the general renderer, including all rendering capabilities and serialization format support. Enabling this feature will automatically enable `all_serde_fmt`.
+
+## Feature `json_serde_fmt`
+
+**Description:**
+
+Enables JSON serde serialization/deserialization formatting support.
+
+## Feature `nightly`
+
+**Description:**
+
+Enables experimental features only available in the Nightly Rust compiler.
+
+## Feature `parser`
+
+**Description:**
+
+Enables the parser module, providing text parsing and analysis capabilities.
+
+When enabled, you can use `Picker` for zero-cost argument extraction, supporting methods like `pick()` and `pick_or()`.
+
+See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-argument-parse)
+
+## Feature `repl`
+
+**Description:**
+
+Enables interactive REPL (Read-Eval-Print Loop) environment support.
+
+When enabled, you can turn your CLI into an interactive shell via `program.exec_repl()`.
+
+See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-repl-basic)
+
+## Feature `ron_serde_fmt`
+
+**Description:**
+
+Enables RON (Rusty Object Notation) serde serialization/deserialization formatting support.
+
+## Feature `toml_serde_fmt`
+
+**Description:**
+
+Enables TOML serde serialization/deserialization formatting support.
+
+## Feature `yaml_serde_fmt`
+
+**Description:**
+
+Enables YAML serde serialization/deserialization formatting support.
+
+<p align="center" style="font-size: 0.85em; color: gray;">
+    Written by @Weicao-CatilGrass
+</p>