From 9b8deaeced4f4a6f7c2492528019cc6e10c379ac Mon Sep 17 00:00:00 2001 From: 魏曹先生 <1992414357@qq.com> Date: Thu, 9 Jul 2026 20:32:59 +0800 Subject: docs: restructure dev-docs sidebar and move pages into subdirectories --- docs/dev-docs/_sidebar.md | 10 +- docs/dev-docs/abouts/.name | 1 - docs/dev-docs/abouts/ai-translation-rule.md | 25 --- docs/dev-docs/abouts/code-verify-system.md | 239 ---------------------- docs/dev-docs/issues/.name | 1 - docs/dev-docs/issues/the-mod-pathfinder.md | 64 ------ docs/dev-docs/issues/the-shit-time.md | 90 -------- docs/dev-docs/pages/abouts/.name | 1 + docs/dev-docs/pages/abouts/ai-translation-rule.md | 25 +++ docs/dev-docs/pages/abouts/code-verify-system.md | 239 ++++++++++++++++++++++ docs/dev-docs/pages/issues/.name | 1 + docs/dev-docs/pages/issues/the-mod-pathfinder.md | 64 ++++++ docs/dev-docs/pages/issues/the-shit-time.md | 90 ++++++++ docs/dev-docs/pages/templates/.name | 0 docs/dev-docs/pages/templates/doc.md | 15 ++ docs/dev-docs/templates/.name | 0 docs/dev-docs/templates/doc.md | 15 -- 17 files changed, 443 insertions(+), 437 deletions(-) delete mode 100644 docs/dev-docs/abouts/.name delete mode 100644 docs/dev-docs/abouts/ai-translation-rule.md delete mode 100644 docs/dev-docs/abouts/code-verify-system.md delete mode 100644 docs/dev-docs/issues/.name delete mode 100644 docs/dev-docs/issues/the-mod-pathfinder.md delete mode 100644 docs/dev-docs/issues/the-shit-time.md create mode 100644 docs/dev-docs/pages/abouts/.name create mode 100644 docs/dev-docs/pages/abouts/ai-translation-rule.md create mode 100644 docs/dev-docs/pages/abouts/code-verify-system.md create mode 100644 docs/dev-docs/pages/issues/.name create mode 100644 docs/dev-docs/pages/issues/the-mod-pathfinder.md create mode 100644 docs/dev-docs/pages/issues/the-shit-time.md create mode 100644 docs/dev-docs/pages/templates/.name create mode 100644 docs/dev-docs/pages/templates/doc.md delete mode 100644 docs/dev-docs/templates/.name delete mode 100644 docs/dev-docs/templates/doc.md diff --git a/docs/dev-docs/_sidebar.md b/docs/dev-docs/_sidebar.md index 76c3649..5c254cd 100644 --- a/docs/dev-docs/_sidebar.md +++ b/docs/dev-docs/_sidebar.md @@ -1,3 +1,9 @@ - [Welcome!](README) -* [The Mod Pathfinder](issues/the-mod-pathfinder) -* [Some Situations Where You'd Be Like "Shit!"](issues/the-shit-time) +* Abouts + * [ai-translation-rule](pages/abouts/ai-translation-rule) + * [code-verify-system](pages/abouts/code-verify-system) +* Issues + * [The Mod Pathfinder](pages/issues/the-mod-pathfinder) + * [Some Situations Where You'd Be Like "Shit!"](pages/issues/the-shit-time) +* templates + * [Title](pages/templates/doc) diff --git a/docs/dev-docs/abouts/.name b/docs/dev-docs/abouts/.name deleted file mode 100644 index d5a4a33..0000000 --- a/docs/dev-docs/abouts/.name +++ /dev/null @@ -1 +0,0 @@ -Abouts diff --git a/docs/dev-docs/abouts/ai-translation-rule.md b/docs/dev-docs/abouts/ai-translation-rule.md deleted file mode 100644 index cc33128..0000000 --- a/docs/dev-docs/abouts/ai-translation-rule.md +++ /dev/null @@ -1,25 +0,0 @@ -# Translation Style Guide - -## 1. Tone & Voice - -- **保持原语气** (Preserve original tone): Maintain the author's attitude, formality, and emotional register exactly as in the source. -- **近似词替换** (Synonymous substitution): Use words with close or equivalent meaning where direct translation is awkward or unnatural. - -## 2. Vocabulary & Abbreviation - -- **缩写** (Abbreviation): Apply standard English abbreviations (e.g., _info_ for information, _dept_ for department) to avoid overlong words, but only when clarity is not sacrificed. -- **简明表述** (Concise expression): Prefer shorter, more common alternatives (e.g., _use_ over _utilize_, _help_ over _facilitate_) unless the original tone demands formality. - -## 3. Structural Rules - -- **段落一致** (Paragraph integrity): Keep the original paragraph breaks and line spacing. -- **标记保留** (Tag preservation): Any inline Markdown formatting (bold, italic, code, links, lists) must be replicated exactly in translation. -- **例示** (Example): - - 原句: “请保持专业语气，但避免使用过长的学术词汇。” - - 译文: “Keep a prof. tone, but avoid long academic words.” -- **最小化改动** (Minimal diff): When translating or syncing English content against a known Chinese original, if the Chinese original's meaning is extremely close to the current English meaning, do not modify the English text. This is to keep git diffs friendly (only modify parts that have truly changed). - -## 4. Exceptions - -- If a term has no common abbreviation, use the full word. -- If preserving tone requires a longer phrase, prioritize tone over brevity. diff --git a/docs/dev-docs/abouts/code-verify-system.md b/docs/dev-docs/abouts/code-verify-system.md deleted file mode 100644 index 7694544..0000000 --- a/docs/dev-docs/abouts/code-verify-system.md +++ /dev/null @@ -1,239 +0,0 @@ -# Doc Code Block Verification System - -This system automatically extracts and compiles Rust code blocks from docs, ensuring all example code stays usable in CI. - -## Config - -Specify which Markdown files to verify via [`verified-docs.toml`](https://github.com/mingling-rs/mingling/blob/main/verified-docs.toml) in the project root. - -You can also test a single file via command-line arg: - -```sh -./run-tools.sh test-all-markdown-code docs/pages/1-getting-started.md -``` - -```powershell -.\run-tools.ps1 test-all-markdown-code docs/pages/1-getting-started.md -``` - -## Default Rules - -Every verified ` ```rust ` code block gets the following injected automatically at compile time — no need to write them explicitly in the block: - -### 1. `#![allow(dead_code)]` and `#![allow(unused)]` - -Added at the top of the generated `main.rs` to suppress dead-code warnings from partial code snippets. - -### 2. `use mingling::prelude::*;` - -If the block already has `use mingling::prelude::*;`, it won't be inserted again. - -Otherwise it's inserted automatically (with `#[allow(unused_imports)]`). - -### 3. `fn main() {}` - -If the block **does not contain** a `fn main` definition, an empty `fn main() {}` is appended, - -so the block can compile as a standalone binary project. - -### 4. `mingling::macros::gen_program!();` - -If the block **does not contain** a `gen_program!()` call, - -`mingling::macros::gen_program!();` is appended automatically. - -This call is required by the mingling framework. - -### 5. Build Cache Dedup — Shared Dep Hash - -Code blocks with the same `Features` and `Dependencies` are automatically grouped into the same compile group, sharing one `Cargo.toml` and build artifacts, avoiding redundant compilations. - -> [!NOTE] -> -> Hash input (all sorted): -> -> 1. Feature list -> 2. External dep name list -> 3. External dep version list -> 4. `name=version` pairs -> -> Uses FNV-1a 64-bit hash, stable across runs. - -## Verification Steps - -After the **default rules** are applied, each block goes through: - -### 1. Block Extraction - -- Only ` ```rust ` fenced code blocks are extracted. -- Empty blocks (no code lines) are skipped. -- Blocks with `// NOT VERIFIED` alone are skipped. - -### 2. Temp Project Generation - -Each block (or each dedup-hash group) gets its own Cargo project: - -``` -.temp/doc-test// -├── Cargo.toml -└── src/ - └── main.rs -``` - -### 3. Build Verification - -Compiled with `cargo build --release`, stderr inherited to the terminal for real-time progress. - -- **Build OK** → **PASS** -- **Build FAIL** → **FAIL**, last 20 lines of error captured. - -### 4. Report - -After all tests, a report is written to `.temp/DOCS-TEST-RESULT.md`, containing: - -- Total tests, passed, failed -- Table of results per block (block #, file, line, status) -- Detailed errors for failed blocks - -### 5. Exit Code - -- Any block fails → non-zero exit code (blocks CI pipeline). -- All pass → zero exit code. - ---- - -## Metadata Tag Rules - -At the start of a ` ```rust ` block (before code content), use these comment headers to declare metadata. Headers are parsed in order; everything after them is treated as code: - -### `// NOT VERIFIED` - -Marks the block **not to be compiled**. Use for illustrative snippets that can't compile on their own. - -```rust -// NOT VERIFIED -// This block is illustrative only, won't be compiled -fn placeholder() {} -``` - -### `// BUILD TIME` - -Marks the block as a `build.rs` script instead of `src/main.rs`. The block code is wrapped in `fn main() { }` and written to `build.rs`. A stub `fn main() {}` is generated for `src/main.rs`. - -```rust -// BUILD TIME -// Features: ["builds", "pathf"] -analyze_and_build_type_mapping().unwrap(); -``` - -### `// Features: [...]` - -Declares the mingling crate features needed by this block, as a JSON string array. These features are written into `Cargo.toml`'s `[dependencies]`. - -```rust -// Features: ["full", "serde"] -``` - -### `// Dependencies:` - -Declares external crate deps needed by the block. After `// Dependencies:`, each dep goes on one line: `// crate_name = "version"`. - -```rust -// Dependencies: -// serde = "1" -// clap = "4" -``` - -> [!TIP] -> -> **Special handling**: -> -> For deps named `serde` or `clap` with a plain string version, -> -> `features = ["derive"]` is auto-added. -> -> If the version uses a TOML inline table (e.g. `{ version = "1", features = ["derive"] }`), -> -> it's kept as-is. - ---- - -## `@@@` Lines (Hidden Compilation) - -Lines starting with `@@@` are **hidden from the rendered documentation** but still included in compilation. - -This is useful when you want to show only the core logic while keeping the block fully compilable: - -```rust -// This line is visible in docs -@@@// This line is hidden but still compiled -@@@fn setup() { /* hidden boilerplate */ } -``` - -### How it works - -| Stage | Handling | -| --------------------- | ------------------------------------------------------------------------------------------------ | -| **docsify rendering** | `@@@` lines are stripped before markdown is rendered (via `beforeEach` plugin) | -| **CI verification** | `@@@` prefix is stripped during block parsing, remaining content is treated as regular Rust code | - -### Convention - -Use `@@@` for: - -- `fn main() {}` / `gen_program!()` when the block doesn't need to show them -- Common `use` imports that would distract from the example -- Type definitions (`pack!`, `#[derive]`) that are necessary for compilation but not the focus -- Helper functions that the reader doesn't need to see - -> [!TIP] -> `@@@` is the replacement for `// NOT VERIFIED` — instead of marking a block as uncompilable, -> hide the boilerplate and keep everything compiling. - ---- - -## Structure Overview - -| Module | Responsibility | -| --------------------------------------------- | ----------------------------------------------------------------------------------- | -| `dev_tools/src/verify.rs` | Block parsing, Cargo.toml/main.rs generation, build exec, hash dedup, report output | -| `dev_tools/src/bin/test-all-markdown-code.rs` | Entry point: read config, collect files, orchestrate tests, aggregate results | -| `verified-docs.toml` | Specifies which doc files to verify | - ---- - -## Full Example - -````markdown -```rust -// Features: ["parser"] -// Dependencies: -// serde = "1" - -// Example code ... -``` -```` - -The above block compiles equivalently to: - -```rust -#![allow(dead_code)] -#![allow(unused)] - -#[allow(unused_imports)] -use mingling::prelude::*; - -// Example code ... - -fn main() {} - -mingling::macros::gen_program!(); -``` - -`Cargo.toml` will contain: - -```toml -[dependencies] -mingling = { path = "../../mingling", features = ["parser"] } -serde = { version = "1", features = ["derive"] } -``` diff --git a/docs/dev-docs/issues/.name b/docs/dev-docs/issues/.name deleted file mode 100644 index f99478d..0000000 --- a/docs/dev-docs/issues/.name +++ /dev/null @@ -1 +0,0 @@ -Issues diff --git a/docs/dev-docs/issues/the-mod-pathfinder.md b/docs/dev-docs/issues/the-mod-pathfinder.md deleted file mode 100644 index 5f8c902..0000000 --- a/docs/dev-docs/issues/the-mod-pathfinder.md +++ /dev/null @@ -1,64 +0,0 @@ -

The Mod Pathfinder

-

- A build-time analyzer that computes full module paths for Mingling types, resolving path ambiguity in macros. -

- -## Background - -Currently, `gen_program!` requires all involved types to be `use`d within their module. Mingling lacks a complete module path analyzer — waiting for `proc-macro-span` to stabilize is clearly not practical, so a solution for obtaining module paths is needed. - -## Solution - -We plan to create an analyzer called `mingling-mod-pathf`, enabled via Mingling's `"pathf"` feature, to compute the full paths of all defined Mingling types. - -### Behavior When Enabled - -**`mingling_core`**: If the `builds` feature is enabled, introduces the `mingling::build::analyze_and_build_type_mapping()` method (analysis completed at Build-Time) - -**`mingling_macros`**: Modifies the behavior of the `gen_program!()` macro — automatically loads the mapping table from the analysis file generated by `mingling::build::analyze_and_build_type_mapping()`, and directly uses the full `mod::path` instead of `TypeName` (injected at Compile-Time) - -## Challenges - -`mingling-mod-pathf` needs to understand **all** Mingling syntax features. -Fortunately, Mingling's type creation is almost always explicit: - -```rust -mod sub { - mingling::macros::pack!(ResultMyName = String); // directly creates ..::sub::ResultMyName -} -``` - -There are a few exceptions, such as the implicit Dispatcher provided by `extra_macros`, but these can be inferred from the node name: - -```rust -dispatcher!("remote.add"); // although the type is unknown, we can infer CMDRemoteAdd and EntryRemoteAdd -``` - -And also `#[program_setup]`: - -```rust -#[program_setup] // can infer CustomSetup from the function name `custom_setup` -fn custom_setup(program: &mut Program) { - program.with_dispatchers((CMD1, CMD2, CMD3, CMD4, CMD5)); -} -``` - -## Pathf Output Format - -Uses TOML key-value pairs, formatted as follows: - -```toml -ResultRemoteAdd = "crate::mymod::ResultRemoteAdd" -``` - -Recommended storage location is under the target directory: - -``` -/target/{target}/{crate-name}/type-mapping.toml -``` - -## Other Issues - -This solution is limited to Mingling's own syntax system. If types like `dispatcher!`, `pack!` are indirectly expanded through macros, the analyzer will not be able to discover them. - -However, this approach solves the current main pain points, so this issue can be set aside for now and addressed later. diff --git a/docs/dev-docs/issues/the-shit-time.md b/docs/dev-docs/issues/the-shit-time.md deleted file mode 100644 index 77a8af9..0000000 --- a/docs/dev-docs/issues/the-shit-time.md +++ /dev/null @@ -1,90 +0,0 @@ -

Some Situations Where You'd Be Like "Shit!"

-

- This document collects the discomforts currently experienced while using Mingling. -

- -This document collects the discomforts currently experienced while using Mingling. - -Of course, you can also contribute to this document. - ---- - -## Why is there no fallback completion logic? - -(completion) (fallback) - -Currently, Mingling's Completion only supports providing completion logic for specific subcommands, with no way to provide global completion. - -For example: - -``` -mycmd -completion: ---help -h --- Display helps ---version -V --- Display versions -``` - -Currently, there is no workaround. - -Ideal solution: - -```rust -#[completion(EntryGlobal)] -fn complete(ctx: &ShellContext) -> Suggest { - // ... -} -``` - ---- - -## Why can't I register descriptions for commands? - -(completion) (dispatcher) - -Currently, Mingling's Completion cannot register a description for each subcommand. - -For example: - -``` -mycmd -completion: -add rm list <--- You cannot register descriptions for commands -``` - -Expected behavior: - -``` -mycmd -completion: -add --- Add something -rm --- Remove something -list --- List something -``` - -Ideal solution: - -```rust -// It should be able to freely integrate with crates that provide i18n functionality, -// so the following approach cannot be used as a data source for descriptions. -dispatcher! { - /// Add Something <--- How to i18n? - "add", CMDAdd => EntryAdd -} - -// Ideally, it should satisfy the following two conditions: -// 1. No need to use `with_dispatcher`, because `with_dispatcher` is disabled in `dispatch_tree` mode -// 2. Must be able to accept String or &str at runtime - -// Current idea -#[inline(always)] -#[dispatcher_desc(EntryAdd)] -fn desc_add() -> String { - // If using rust_i18n - t!("cmd.add.desc") -} - -// Collected and generated by `gen_program!()` -// Generate something like get_dispatcher_desc(id: &ThisProgram) -> String -// Match the corresponding function using enum values inside ThisProgram -gen_program!() -``` diff --git a/docs/dev-docs/pages/abouts/.name b/docs/dev-docs/pages/abouts/.name new file mode 100644 index 0000000..d5a4a33 --- /dev/null +++ b/docs/dev-docs/pages/abouts/.name @@ -0,0 +1 @@ +Abouts diff --git a/docs/dev-docs/pages/abouts/ai-translation-rule.md b/docs/dev-docs/pages/abouts/ai-translation-rule.md new file mode 100644 index 0000000..cc33128 --- /dev/null +++ b/docs/dev-docs/pages/abouts/ai-translation-rule.md @@ -0,0 +1,25 @@ +# Translation Style Guide + +## 1. Tone & Voice + +- **保持原语气** (Preserve original tone): Maintain the author's attitude, formality, and emotional register exactly as in the source. +- **近似词替换** (Synonymous substitution): Use words with close or equivalent meaning where direct translation is awkward or unnatural. + +## 2. Vocabulary & Abbreviation + +- **缩写** (Abbreviation): Apply standard English abbreviations (e.g., _info_ for information, _dept_ for department) to avoid overlong words, but only when clarity is not sacrificed. +- **简明表述** (Concise expression): Prefer shorter, more common alternatives (e.g., _use_ over _utilize_, _help_ over _facilitate_) unless the original tone demands formality. + +## 3. Structural Rules + +- **段落一致** (Paragraph integrity): Keep the original paragraph breaks and line spacing. +- **标记保留** (Tag preservation): Any inline Markdown formatting (bold, italic, code, links, lists) must be replicated exactly in translation. +- **例示** (Example): + - 原句: “请保持专业语气，但避免使用过长的学术词汇。” + - 译文: “Keep a prof. tone, but avoid long academic words.” +- **最小化改动** (Minimal diff): When translating or syncing English content against a known Chinese original, if the Chinese original's meaning is extremely close to the current English meaning, do not modify the English text. This is to keep git diffs friendly (only modify parts that have truly changed). + +## 4. Exceptions + +- If a term has no common abbreviation, use the full word. +- If preserving tone requires a longer phrase, prioritize tone over brevity. diff --git a/docs/dev-docs/pages/abouts/code-verify-system.md b/docs/dev-docs/pages/abouts/code-verify-system.md new file mode 100644 index 0000000..7694544 --- /dev/null +++ b/docs/dev-docs/pages/abouts/code-verify-system.md @@ -0,0 +1,239 @@ +# Doc Code Block Verification System + +This system automatically extracts and compiles Rust code blocks from docs, ensuring all example code stays usable in CI. + +## Config + +Specify which Markdown files to verify via [`verified-docs.toml`](https://github.com/mingling-rs/mingling/blob/main/verified-docs.toml) in the project root. + +You can also test a single file via command-line arg: + +```sh +./run-tools.sh test-all-markdown-code docs/pages/1-getting-started.md +``` + +```powershell +.\run-tools.ps1 test-all-markdown-code docs/pages/1-getting-started.md +``` + +## Default Rules + +Every verified ` ```rust ` code block gets the following injected automatically at compile time — no need to write them explicitly in the block: + +### 1. `#![allow(dead_code)]` and `#![allow(unused)]` + +Added at the top of the generated `main.rs` to suppress dead-code warnings from partial code snippets. + +### 2. `use mingling::prelude::*;` + +If the block already has `use mingling::prelude::*;`, it won't be inserted again. + +Otherwise it's inserted automatically (with `#[allow(unused_imports)]`). + +### 3. `fn main() {}` + +If the block **does not contain** a `fn main` definition, an empty `fn main() {}` is appended, + +so the block can compile as a standalone binary project. + +### 4. `mingling::macros::gen_program!();` + +If the block **does not contain** a `gen_program!()` call, + +`mingling::macros::gen_program!();` is appended automatically. + +This call is required by the mingling framework. + +### 5. Build Cache Dedup — Shared Dep Hash + +Code blocks with the same `Features` and `Dependencies` are automatically grouped into the same compile group, sharing one `Cargo.toml` and build artifacts, avoiding redundant compilations. + +> [!NOTE] +> +> Hash input (all sorted): +> +> 1. Feature list +> 2. External dep name list +> 3. External dep version list +> 4. `name=version` pairs +> +> Uses FNV-1a 64-bit hash, stable across runs. + +## Verification Steps + +After the **default rules** are applied, each block goes through: + +### 1. Block Extraction + +- Only ` ```rust ` fenced code blocks are extracted. +- Empty blocks (no code lines) are skipped. +- Blocks with `// NOT VERIFIED` alone are skipped. + +### 2. Temp Project Generation + +Each block (or each dedup-hash group) gets its own Cargo project: + +``` +.temp/doc-test// +├── Cargo.toml +└── src/ + └── main.rs +``` + +### 3. Build Verification + +Compiled with `cargo build --release`, stderr inherited to the terminal for real-time progress. + +- **Build OK** → **PASS** +- **Build FAIL** → **FAIL**, last 20 lines of error captured. + +### 4. Report + +After all tests, a report is written to `.temp/DOCS-TEST-RESULT.md`, containing: + +- Total tests, passed, failed +- Table of results per block (block #, file, line, status) +- Detailed errors for failed blocks + +### 5. Exit Code + +- Any block fails → non-zero exit code (blocks CI pipeline). +- All pass → zero exit code. + +--- + +## Metadata Tag Rules + +At the start of a ` ```rust ` block (before code content), use these comment headers to declare metadata. Headers are parsed in order; everything after them is treated as code: + +### `// NOT VERIFIED` + +Marks the block **not to be compiled**. Use for illustrative snippets that can't compile on their own. + +```rust +// NOT VERIFIED +// This block is illustrative only, won't be compiled +fn placeholder() {} +``` + +### `// BUILD TIME` + +Marks the block as a `build.rs` script instead of `src/main.rs`. The block code is wrapped in `fn main() { }` and written to `build.rs`. A stub `fn main() {}` is generated for `src/main.rs`. + +```rust +// BUILD TIME +// Features: ["builds", "pathf"] +analyze_and_build_type_mapping().unwrap(); +``` + +### `// Features: [...]` + +Declares the mingling crate features needed by this block, as a JSON string array. These features are written into `Cargo.toml`'s `[dependencies]`. + +```rust +// Features: ["full", "serde"] +``` + +### `// Dependencies:` + +Declares external crate deps needed by the block. After `// Dependencies:`, each dep goes on one line: `// crate_name = "version"`. + +```rust +// Dependencies: +// serde = "1" +// clap = "4" +``` + +> [!TIP] +> +> **Special handling**: +> +> For deps named `serde` or `clap` with a plain string version, +> +> `features = ["derive"]` is auto-added. +> +> If the version uses a TOML inline table (e.g. `{ version = "1", features = ["derive"] }`), +> +> it's kept as-is. + +--- + +## `@@@` Lines (Hidden Compilation) + +Lines starting with `@@@` are **hidden from the rendered documentation** but still included in compilation. + +This is useful when you want to show only the core logic while keeping the block fully compilable: + +```rust +// This line is visible in docs +@@@// This line is hidden but still compiled +@@@fn setup() { /* hidden boilerplate */ } +``` + +### How it works + +| Stage | Handling | +| --------------------- | ------------------------------------------------------------------------------------------------ | +| **docsify rendering** | `@@@` lines are stripped before markdown is rendered (via `beforeEach` plugin) | +| **CI verification** | `@@@` prefix is stripped during block parsing, remaining content is treated as regular Rust code | + +### Convention + +Use `@@@` for: + +- `fn main() {}` / `gen_program!()` when the block doesn't need to show them +- Common `use` imports that would distract from the example +- Type definitions (`pack!`, `#[derive]`) that are necessary for compilation but not the focus +- Helper functions that the reader doesn't need to see + +> [!TIP] +> `@@@` is the replacement for `// NOT VERIFIED` — instead of marking a block as uncompilable, +> hide the boilerplate and keep everything compiling. + +--- + +## Structure Overview + +| Module | Responsibility | +| --------------------------------------------- | ----------------------------------------------------------------------------------- | +| `dev_tools/src/verify.rs` | Block parsing, Cargo.toml/main.rs generation, build exec, hash dedup, report output | +| `dev_tools/src/bin/test-all-markdown-code.rs` | Entry point: read config, collect files, orchestrate tests, aggregate results | +| `verified-docs.toml` | Specifies which doc files to verify | + +--- + +## Full Example + +````markdown +```rust +// Features: ["parser"] +// Dependencies: +// serde = "1" + +// Example code ... +``` +```` + +The above block compiles equivalently to: + +```rust +#![allow(dead_code)] +#![allow(unused)] + +#[allow(unused_imports)] +use mingling::prelude::*; + +// Example code ... + +fn main() {} + +mingling::macros::gen_program!(); +``` + +`Cargo.toml` will contain: + +```toml +[dependencies] +mingling = { path = "../../mingling", features = ["parser"] } +serde = { version = "1", features = ["derive"] } +``` diff --git a/docs/dev-docs/pages/issues/.name b/docs/dev-docs/pages/issues/.name new file mode 100644 index 0000000..f99478d --- /dev/null +++ b/docs/dev-docs/pages/issues/.name @@ -0,0 +1 @@ +Issues diff --git a/docs/dev-docs/pages/issues/the-mod-pathfinder.md b/docs/dev-docs/pages/issues/the-mod-pathfinder.md new file mode 100644 index 0000000..5f8c902 --- /dev/null +++ b/docs/dev-docs/pages/issues/the-mod-pathfinder.md @@ -0,0 +1,64 @@ +

The Mod Pathfinder

+

+ A build-time analyzer that computes full module paths for Mingling types, resolving path ambiguity in macros. +

+ +## Background + +Currently, `gen_program!` requires all involved types to be `use`d within their module. Mingling lacks a complete module path analyzer — waiting for `proc-macro-span` to stabilize is clearly not practical, so a solution for obtaining module paths is needed. + +## Solution + +We plan to create an analyzer called `mingling-mod-pathf`, enabled via Mingling's `"pathf"` feature, to compute the full paths of all defined Mingling types. + +### Behavior When Enabled + +**`mingling_core`**: If the `builds` feature is enabled, introduces the `mingling::build::analyze_and_build_type_mapping()` method (analysis completed at Build-Time) + +**`mingling_macros`**: Modifies the behavior of the `gen_program!()` macro — automatically loads the mapping table from the analysis file generated by `mingling::build::analyze_and_build_type_mapping()`, and directly uses the full `mod::path` instead of `TypeName` (injected at Compile-Time) + +## Challenges + +`mingling-mod-pathf` needs to understand **all** Mingling syntax features. +Fortunately, Mingling's type creation is almost always explicit: + +```rust +mod sub { + mingling::macros::pack!(ResultMyName = String); // directly creates ..::sub::ResultMyName +} +``` + +There are a few exceptions, such as the implicit Dispatcher provided by `extra_macros`, but these can be inferred from the node name: + +```rust +dispatcher!("remote.add"); // although the type is unknown, we can infer CMDRemoteAdd and EntryRemoteAdd +``` + +And also `#[program_setup]`: + +```rust +#[program_setup] // can infer CustomSetup from the function name `custom_setup` +fn custom_setup(program: &mut Program) { + program.with_dispatchers((CMD1, CMD2, CMD3, CMD4, CMD5)); +} +``` + +## Pathf Output Format + +Uses TOML key-value pairs, formatted as follows: + +```toml +ResultRemoteAdd = "crate::mymod::ResultRemoteAdd" +``` + +Recommended storage location is under the target directory: + +``` +/target/{target}/{crate-name}/type-mapping.toml +``` + +## Other Issues + +This solution is limited to Mingling's own syntax system. If types like `dispatcher!`, `pack!` are indirectly expanded through macros, the analyzer will not be able to discover them. + +However, this approach solves the current main pain points, so this issue can be set aside for now and addressed later. diff --git a/docs/dev-docs/pages/issues/the-shit-time.md b/docs/dev-docs/pages/issues/the-shit-time.md new file mode 100644 index 0000000..77a8af9 --- /dev/null +++ b/docs/dev-docs/pages/issues/the-shit-time.md @@ -0,0 +1,90 @@ +

Some Situations Where You'd Be Like "Shit!"

+

+ This document collects the discomforts currently experienced while using Mingling. +

+ +This document collects the discomforts currently experienced while using Mingling. + +Of course, you can also contribute to this document. + +--- + +## Why is there no fallback completion logic? + +(completion) (fallback) + +Currently, Mingling's Completion only supports providing completion logic for specific subcommands, with no way to provide global completion. + +For example: + +``` +mycmd +completion: +--help -h --- Display helps +--version -V --- Display versions +``` + +Currently, there is no workaround. + +Ideal solution: + +```rust +#[completion(EntryGlobal)] +fn complete(ctx: &ShellContext) -> Suggest { + // ... +} +``` + +--- + +## Why can't I register descriptions for commands? + +(completion) (dispatcher) + +Currently, Mingling's Completion cannot register a description for each subcommand. + +For example: + +``` +mycmd +completion: +add rm list <--- You cannot register descriptions for commands +``` + +Expected behavior: + +``` +mycmd +completion: +add --- Add something +rm --- Remove something +list --- List something +``` + +Ideal solution: + +```rust +// It should be able to freely integrate with crates that provide i18n functionality, +// so the following approach cannot be used as a data source for descriptions. +dispatcher! { + /// Add Something <--- How to i18n? + "add", CMDAdd => EntryAdd +} + +// Ideally, it should satisfy the following two conditions: +// 1. No need to use `with_dispatcher`, because `with_dispatcher` is disabled in `dispatch_tree` mode +// 2. Must be able to accept String or &str at runtime + +// Current idea +#[inline(always)] +#[dispatcher_desc(EntryAdd)] +fn desc_add() -> String { + // If using rust_i18n + t!("cmd.add.desc") +} + +// Collected and generated by `gen_program!()` +// Generate something like get_dispatcher_desc(id: &ThisProgram) -> String +// Match the corresponding function using enum values inside ThisProgram +gen_program!() +``` diff --git a/docs/dev-docs/pages/templates/.name b/docs/dev-docs/pages/templates/.name new file mode 100644 index 0000000..e69de29 diff --git a/docs/dev-docs/pages/templates/doc.md b/docs/dev-docs/pages/templates/doc.md new file mode 100644 index 0000000..6a56bbd --- /dev/null +++ b/docs/dev-docs/pages/templates/doc.md @@ -0,0 +1,15 @@ +

Title

+

+ Description +

+ +Content here + + + + +

+ Written by @Your-Name +

diff --git a/docs/dev-docs/templates/.name b/docs/dev-docs/templates/.name deleted file mode 100644 index e69de29..0000000 diff --git a/docs/dev-docs/templates/doc.md b/docs/dev-docs/templates/doc.md deleted file mode 100644 index 6a56bbd..0000000 --- a/docs/dev-docs/templates/doc.md +++ /dev/null @@ -1,15 +0,0 @@ -

Title

-

- Description -

- -Content here - - - - -

- Written by @Your-Name -

-- cgit