docs(mingling): move crate-level docs to separate lib.md

3 files changed, 106 insertions, 74 deletions

diff --git a/arg_picker/src/corebind/entry_picker.rs b/arg_picker/src/corebind/entry_picker.rs
index 69bc4d8..d543f98 100644
--- a/arg_picker/src/corebind/entry_picker.rs
+++ b/arg_picker/src/corebind/entry_picker.rs
@@ -30,7 +30,7 @@ pub trait EntryPicker<'a, This> {
     ///
     /// # Parameters
     ///
-    /// * `arg` — The argument definition, typically obtained from [`crate::arg`].
+    /// * `arg` — The argument definition, typically obtained from [`crate::macros::arg`].
     fn pick<Next>(
         self,
         arg: impl Into<&'a PickerArg<'a, Next>>,
@@ -53,7 +53,7 @@ pub trait EntryPicker<'a, This> {
     ///
     /// # Parameters
     ///
-    /// * `arg` — The argument definition, typically obtained from [`crate::arg`].
+    /// * `arg` — The argument definition, typically obtained from [`crate::macros::arg`].
     /// * `func` — A closure that provides a default value if the arg is not provided by the user.
     fn pick_or<Next, F>(
         self,
@@ -78,7 +78,7 @@ pub trait EntryPicker<'a, This> {
     ///
     /// # Parameters
     ///
-    /// * `arg` — The argument definition, typically obtained from [`crate::arg`].
+    /// * `arg` — The argument definition, typically obtained from [`crate::macros::arg`].
     fn pick_or_default<Next>(
         self,
         arg: impl Into<&'a PickerArg<'a, Next>>,
@@ -100,7 +100,7 @@ pub trait EntryPicker<'a, This> {
     ///
     /// # Parameters
     ///
-    /// * `arg` — The argument definition, typically obtained from [`crate::arg`].
+    /// * `arg` — The argument definition, typically obtained from [`crate::macros::arg`].
     /// * `func` — A closure that produces a route value if the arg is not provided by the user.
     fn pick_or_route<Next, F>(
         self,
diff --git a/mingling/src/lib.md b/mingling/src/lib.md
new file mode 100644
index 0000000..0fcf811
--- /dev/null
+++ b/mingling/src/lib.md
@@ -0,0 +1,101 @@
+<p align="center">
+    <a href="https://github.com/mingling-rs/mingling">
+        <img alt="Mingling" src="https://github.com/mingling-rs/mingling/raw/main/docs/res/icon2.png" width="50%">
+    </a>
+</p>
+<h1 align="center">Mìng Lìng - 命令</h1>
+
+<p align="center">
+    <b>/mɪŋ lɪŋ/</b>
+</p>
+
+<p align="center">
+    Macro magician in your CLI.
+</p>
+
+## Intro
+
+[`Mingling`](https://github.com/mingling-rs/mingling) is a **proc-macro and type system-based** Rust CLI framework, suitable for developing complex command-line programs with numerous subcommands.
+
+## Use
+
+Here is a basic project written using **Mingling**:
+
+- When the user types `greet`, the program outputs `Hello, World!`
+- When the user types `greet Alice`, the program outputs `Hello, Alice!`
+
+```rust
+use mingling::prelude::*;
+
+dispatcher!("greet", CMDGreet => EntryGreet);
+
+fn main() {
+    let mut program = ThisProgram::new();
+    program.with_dispatcher(CMDGreet);
+    program.exec_and_exit();
+}
+
+pack!(ResultName = String);
+
+#[chain]
+fn handle_greet(args: EntryGreet) -> Next {
+    let name: ResultName = args
+        .inner
+        .first()
+        .cloned()
+        .unwrap_or_else(|| "World".to_string())
+        .into();
+    name
+}
+
+#[renderer]
+fn render_name(name: ResultName) -> RenderResult {
+    let mut result = RenderResult::default();
+    result.println(&format!("Hello, {}!", *name));
+    result
+}
+
+#[renderer]
+fn render_dispatcher_not_found(err: ErrorDispatcherNotFound) -> RenderResult {
+    let mut result = RenderResult::default();
+    if err.len() > 0 {
+        result.println(&format!("Command not found: [{}]", err.join(" ")));
+    }
+    result
+}
+
+gen_program!();
+```
+
+Output:
+
+```text
+> mycmd greet
+Hello, World!
+> mycmd greet Alice
+Hello, Alice!
+> mycmd great
+Command not found: [great]
+```
+
+## Examples
+
+`Mingling` provides detailed usage examples for your reference.
+See [Examples](_mingling_examples/index.html) or [Helpdoc](https://mingling-rs.github.io/mingling/docs/examples.html)
+
+## About Features
+
+All features of `Mingling` are opt-in. To learn what each feature provides, see [Features](feature/index.html) or [Helpdoc](https://mingling-rs.github.io/mingling/docs/doc.html#/pages/other/features)
+
+## Use unreleased version
+
+If you want to use the latest development version, you can pull from the [Unreleased](https://github.com/mingling-rs/mingling/tree/unreleased) branch on [GitHub](https://github.com/mingling-rs/mingling) by adding the following to your `Cargo.toml`:
+
+```toml
+[dependencies.mingling]
+git = "https://github.com/mingling-rs/mingling.git"
+tag = "unreleased"
+features = []
+```
+
+**Please note** that the documentation for the latest version may differ from this article. It is recommended to refer to the [latest documentation](https://mingling-rs.github.io/mingling/docs/api-docs/mingling/).
diff --git a/mingling/src/lib.rs b/mingling/src/lib.rs
index 44812d6..718d282 100644
--- a/mingling/src/lib.rs
+++ b/mingling/src/lib.rs
@@ -1,73 +1,4 @@
-//! Mingling
-//!
-//! # Intro
-//! [`Mingling`](https://github.com/mingling-rs/mingling) is a **proc-macro and type system-based** Rust CLI framework, suitable for developing complex command-line programs with numerous subcommands.
-//!
-//! # Use
-//! Here is a basic project written using **Mingling**:
-//! - When the user types `greet`, the program outputs `Hello, World!`
-//! - When the user types `greet Alice`, the program outputs `Hello, Alice!`
-//!
-//! ```rust
-//! use mingling::prelude::*;
-//!
-//! dispatcher!("greet", CMDGreet => EntryGreet);
-//!
-//! fn main() {
-//!     let mut program = ThisProgram::new();
-//!     program.with_dispatcher(CMDGreet);
-//!     program.exec_and_exit();
-//! }
-//!
-//! pack!(ResultName = String);
-//!
-//! #[chain]
-//! fn handle_greet(args: EntryGreet) -> Next {
-//!     let name: ResultName = args
-//!         .inner
-//!         .first()
-//!         .cloned()
-//!         .unwrap_or_else(|| "World".to_string())
-//!         .into();
-//!     name
-//! }
-//!
-//! #[renderer]
-//! fn render_name(name: ResultName) -> RenderResult {
-//!     let mut result = RenderResult::default();
-//!     result.println(&format!("Hello, {}!", *name));
-//!     result
-//! }
-//!
-//! #[renderer]
-//! fn render_dispatcher_not_found(err: ErrorDispatcherNotFound) -> RenderResult {
-//!     let mut result = RenderResult::default();
-//!     if err.len() > 0 {
-//!         result.println(&format!("Command not found: [{}]", err.join(" ")));
-//!     }
-//!     result
-//! }
-//!
-//! gen_program!();
-//! ```
-//!
-//! Output:
-//!
-//! ```text
-//! > mycmd greet
-//! Hello, World!
-//! > mycmd greet Alice
-//! Hello, Alice!
-//! > mycmd great
-//! Command not found: [great]
-//! ```
-//!
-//! # Examples
-//! `Mingling` provides detailed usage examples for your reference.
-//! See [Examples](_mingling_examples/index.html) or [Helpdoc](https://mingling-rs.github.io/mingling/docs/examples.html)
-//!
-//! # About Features
-//! All features of `Mingling` are opt-in. To learn what each feature provides, see [Features](feature/index.html) or [Helpdoc](https://mingling-rs.github.io/mingling/docs/doc.html#/pages/other/features)
+#![doc = include_str!("lib.md")]
 
 #[cfg(feature = "core")]
 mod example_docs;