diff options
| -rw-r--r-- | docs/README.md | 33 | ||||
| -rw-r--r-- | docs/_sidebar.md | 3 | ||||
| -rw-r--r-- | docs/_zh_CN/README.md | 33 | ||||
| -rw-r--r-- | docs/_zh_CN/_sidebar.md | 3 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/1-getting-started.md (renamed from docs/_zh_CN/pages/2-getting-started.md) | 9 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/1-intro.md | 32 | ||||
| -rw-r--r-- | docs/pages/1-getting-started.md (renamed from docs/pages/2-getting-started.md) | 7 | ||||
| -rw-r--r-- | docs/pages/1-intro.md | 32 |
8 files changed, 83 insertions, 69 deletions
diff --git a/docs/README.md b/docs/README.md index 15c072e..4e327c3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,3 +3,36 @@ <p align="center"> This is documentation for the <b>Mingling</b> command-line framework, maintained by <a href="https://github.com/Weicao-CatilGrass">Weicao-CatilGrass</a> </p> + +## Intro + +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/_sidebar.md b/docs/_sidebar.md index d60a631..47f46b8 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,6 +1,5 @@ - [Welcome!](README) -* [Introduction](pages/1-intro) -* [Getting Started](pages/2-getting-started) +* [Getting Started](pages/1-getting-started) * Other * [Features](pages/other/features) * [Naming Conventions](pages/other/naming_rule) diff --git a/docs/_zh_CN/README.md b/docs/_zh_CN/README.md index b302220..b529a86 100644 --- a/docs/_zh_CN/README.md +++ b/docs/_zh_CN/README.md @@ -3,3 +3,36 @@ <p align="center"> 该页面为 <b>Mingling</b> 命令行框架的中文文档，由 <a href="https://github.com/Weicao-CatilGrass">Weicao-CatilGrass</a> 维护 </p> + +## 前言 + +如果你正被这些问题困扰—— + +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/_sidebar.md b/docs/_zh_CN/_sidebar.md index 1fd2e13..620b11c 100644 --- a/docs/_zh_CN/_sidebar.md +++ b/docs/_zh_CN/_sidebar.md @@ -1,6 +1,5 @@ - [Welcome!](README) -* [介绍](pages/1-intro) -* [起步](pages/2-getting-started) +* [起步](pages/1-getting-started) * 其他 * [特性](pages/other/features) * [命名规范](pages/other/naming_rule) diff --git a/docs/_zh_CN/pages/2-getting-started.md b/docs/_zh_CN/pages/1-getting-started.md index 62eb94b..2961464 100644 --- a/docs/_zh_CN/pages/2-getting-started.md +++ b/docs/_zh_CN/pages/1-getting-started.md @@ -44,13 +44,20 @@ use mingling::prelude::*; fn main() { let mut program = ThisProgram::new(); - + program.exec_and_exit(); } gen_program!(); ``` +> [!IMPORTANT] +> 文档中几乎所有 Rust 代码块都已在 CI 流程中编译通过，可以保证可用性。 +> +> 但以 `// NOT VERIFIED` 开头的代码块 **未被验证**。 +> +> 想确认哪些 `*.md` 文件被编译过？请看 [`verified-docs.toml`](https://github.com/mingling-rs/mingling/blob/main/verified-docs.toml) + ## 编译验证 ```plaintext diff --git a/docs/_zh_CN/pages/1-intro.md b/docs/_zh_CN/pages/1-intro.md deleted file mode 100644 index 7210d2e..0000000 --- a/docs/_zh_CN/pages/1-intro.md +++ /dev/null @@ -1,32 +0,0 @@ -<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/pages/2-getting-started.md b/docs/pages/1-getting-started.md index 35da464..4832191 100644 --- a/docs/pages/2-getting-started.md +++ b/docs/pages/1-getting-started.md @@ -51,6 +51,13 @@ fn main() { gen_program!(); ``` +> [!IMPORTANT] +> Almost all Rust code blocks in the documentation have been compiled through the CI pipeline and are guaranteed to be usable. +> +> However, code blocks starting with `// NOT VERIFIED` have **not been verified**. +> +> Want to know which `*.md` files have been compiled? Check [`verified-docs.toml`](https://github.com/mingling-rs/mingling/blob/main/verified-docs.toml) + ## Verify Compilation ```plaintext diff --git a/docs/pages/1-intro.md b/docs/pages/1-intro.md deleted file mode 100644 index edf83bb..0000000 --- a/docs/pages/1-intro.md +++ /dev/null @@ -1,32 +0,0 @@ -<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? |