diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_zh_CN/index.html | 2 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/12-exit-code.md | 4 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/advanced/1-completion.md | 21 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/other/features.md | 64 | ||||
| -rw-r--r-- | docs/dev/README.md | 2 | ||||
| -rw-r--r-- | docs/dev/index.html | 2 | ||||
| -rw-r--r-- | docs/dev/pages/abouts/ci.md | 148 | ||||
| -rw-r--r-- | docs/dev/pages/abouts/code-verify-system.md | 58 | ||||
| -rw-r--r-- | docs/example-viewer.html | 4 | ||||
| -rw-r--r-- | docs/examples.html | 4 | ||||
| -rw-r--r-- | docs/examples.json (renamed from docs/example-pages/examples.json) | 11 | ||||
| -rw-r--r-- | docs/index.html (renamed from docs/doc.html) | 0 | ||||
| -rw-r--r-- | docs/licenses/docsify.md (renamed from docs/LICENSE) | 0 | ||||
| -rw-r--r-- | docs/pages/12-exit-code.md | 4 | ||||
| -rw-r--r-- | docs/pages/advanced/1-completion.md | 21 | ||||
| -rw-r--r-- | docs/pages/other/features.md | 64 |
16 files changed, 182 insertions, 227 deletions
diff --git a/docs/_zh_CN/index.html b/docs/_zh_CN/index.html index ad21062..d0b9234 100644 --- a/docs/_zh_CN/index.html +++ b/docs/_zh_CN/index.html @@ -41,7 +41,7 @@ " >🌗 主题</a > - <a href="../doc.html"><b>English Docs</b></a> + <a href="../index.html"><b>English Docs</b></a> </nav> <div id="app"></div> diff --git a/docs/_zh_CN/pages/12-exit-code.md b/docs/_zh_CN/pages/12-exit-code.md index 9270b84..1f9e05c 100644 --- a/docs/_zh_CN/pages/12-exit-code.md +++ b/docs/_zh_CN/pages/12-exit-code.md @@ -12,7 +12,7 @@ @@@use mingling::setup::ExitCodeSetup; fn main() { let mut program = ThisProgram::new(); - program.with_setup(ExitCodeSetup::default()); + program.with_setup(ExitCodeSetup); @@@ program.exec_and_exit(); } ``` @@ -55,7 +55,7 @@ fn handle_check(_args: EntryCheck, ec: &mut ResExitCode) { @@@use mingling::setup::ExitCodeSetup; fn main() { let mut program = ThisProgram::new(); - program.with_setup(ExitCodeSetup::default()); + program.with_setup(ExitCodeSetup); // 获取退出码自行处理 let exit_code = program.exec(); diff --git a/docs/_zh_CN/pages/advanced/1-completion.md b/docs/_zh_CN/pages/advanced/1-completion.md index 28587b3..290fab0 100644 --- a/docs/_zh_CN/pages/advanced/1-completion.md +++ b/docs/_zh_CN/pages/advanced/1-completion.md @@ -11,13 +11,6 @@ Mingling 的补全是**完全动态**的——没有静态的补全文件，而 # Cargo.toml [dependencies.mingling] features = ["comp"] - -[build-dependencies.mingling] -features = [ - "comp", - # 启用 `build` 特性以提供构建期支持 - "build" -] ``` ## 工作原理 @@ -43,7 +36,7 @@ features = [ @@@dispatcher!("greet", EntryGreet); #[completion(EntryGreet)] -fn complete_greet(ctx: &ShellContext) -> Suggest { +fn complete_greet(ctx: ShellContext) -> Suggest { if ctx.previous_word == "greet" { let mut items = BTreeSet::new(); items.insert(SuggestItem::new_with_desc("Alice".into(), "Likes to receive messages".into())); @@ -72,8 +65,18 @@ suggest! { ## 生成补全脚本 -在 `build.rs` 中调用 `build_comp_scripts` 生成补全脚本（需要 `builds` + `comp` 特性）。 +开启 `comp` 特性后，`gen_program!()` 会在编译期自动调用 `build_comp!()`，生成以 `CARGO_PKG_NAME` 命名的补全脚本到 `target/mingling/`。 + +如果你的二进制名与 crate 名不同，可以手动调用 `build_comp!()` 并指定二进制名： +```rust +// Features: ["comp"] +@@@use mingling::macros::build_comp; +@@@fn example() { +build_comp!("mybin"); +@@@} +``` + 详见 [example-completion](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-completion)。 <p align="center" style="font-size: 0.85em; color: gray;"> diff --git a/docs/_zh_CN/pages/other/features.md b/docs/_zh_CN/pages/other/features.md index 5fa7c86..f8753e5 100644 --- a/docs/_zh_CN/pages/other/features.md +++ b/docs/_zh_CN/pages/other/features.md @@ -25,42 +25,6 @@ Mingling 提供了一系列**预设特性组**，方便用户按需组合启用 **定位：** 完整模式，启用 Mingling 的全部核心功能。在 `advanced` 的基础上额外包含 clap 集成、完整的结构化渲染器（含所有序列化格式）以及实验性的路径分析器，适合大型、功能全面的命令行应用。 -## `build_advanced` - -**启用特性：** `build`、`comp` - -**定位：** 构建期增强配置，用于在项目构建时生成补全脚本等构建辅助材料（`comp` 特性提供补全脚本生成能力）。 - -> [!NOTE] -> -> 此特性组为**构建依赖**专用，需配合 `advanced` 特性使用。请在 `Cargo.toml` 的 `[build-dependencies]` 中启用： - -```toml -[dependencies.mingling] -features = ["advanced"] - -[build-dependencies.mingling] -features = ["build_advanced"] -``` - -## `build_full` - -**启用特性：** `build`、`comp`、`pathf`、`dispatch_tree` - -**定位：** 完整的构建期配置，在 `build_advanced` 的基础上额外包含路径分析器（`pathf`）以自动解析类型模块路径，适合结构复杂、需要自动化构建期分析的项目。 - -> [!NOTE] -> -> 此特性组为**构建依赖**专用，需配合 `full` 特性使用。请在 `Cargo.toml` 的 `[build-dependencies]` 中启用： - -```toml -[dependencies.mingling] -features = ["full"] - -[build-dependencies.mingling] -features = ["build_full"] -``` - # 特性详解 ## 特性 `all_serde_fmt` @@ -91,23 +55,6 @@ async fn handle_state_foo(foo: StateFoo) -> Next { 详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-async-support) -## 特性 `builds` - -**介绍:** - -启用部分需要在 `build.rs` 使用的脚本，目前包含： - -1. `comp` 特性下的补全脚本生成： - -```rust -// BUILD TIME -// Features: ["builds", "comp"] -use mingling::build::build_comp_scripts; - -// 为 `myprogram` 生成补全脚本 -build_comp_scripts("myprogram").unwrap(); -``` - ## 特性 `clap` **介绍:** @@ -318,17 +265,10 @@ pub struct ErrorNotDir(PathBuf); # Cargo.toml [dependencies.mingling] features = ["pathf"] - -[build-dependencies.mingling] -features = ["builds", "pathf"] -``` - -```rust -// BUILD TIME -// Features: ["pathf"] -analyze_and_build_type_mapping().unwrap(); ``` +开启 `pathf` 特性后，`gen_program!()` 会在编译期自动调用 `build_pathf!()` 执行类型映射分析。 + 详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-pathfinder) ## 特性 `picker` diff --git a/docs/dev/README.md b/docs/dev/README.md index 9289fcf..29b7568 100644 --- a/docs/dev/README.md +++ b/docs/dev/README.md @@ -4,7 +4,7 @@ Internal development documentation for the <b>Mingling</b> codebase — design notes, issue discussions, and architectural decisions. </p> -This site is separate from the [Helpdoc](https://mingling-rs.github.io/mingling/docs/doc.html). +This site is separate from the [Helpdoc](https://mingling-rs.github.io/mingling/docs/index.html). The helpdoc is user-facing: `tutorials`, `feature guides`, and `how-to content` for developers _using_ Mingling to build CLI applications. diff --git a/docs/dev/index.html b/docs/dev/index.html index 1bfb5c5..327e397 100644 --- a/docs/dev/index.html +++ b/docs/dev/index.html @@ -125,7 +125,7 @@ " >🌓 Theme</a > - <a href="../doc.html">📖 Helpdoc</a> + <a href="../index.html">📖 Helpdoc</a> </nav> <div id="app"></div> diff --git a/docs/dev/pages/abouts/ci.md b/docs/dev/pages/abouts/ci.md index 9f638d7..37015eb 100644 --- a/docs/dev/pages/abouts/ci.md +++ b/docs/dev/pages/abouts/ci.md @@ -3,9 +3,9 @@ CI workflow and local execution guide for Mingling </p> -Mingling's CI process is built into the project, with its execution logic located in `.run/src/bin/ci.rs`. You can run it locally via the `cargo ci` command, which produces the same results as the `CI` workflow in GitHub Actions. +Mingling's CI process is built into the project itself: the execution logic lives in `dev/ci/`, a separate crate **built on the Mingling framework** — it dogfoods the very library it validates. You can run it locally via the `cargo ci` command, which produces the same results as the `CI` workflow in GitHub Actions. -During development, you can run `cargo ci` at any time to verify that your code hasn't introduced regressions. +During development, you can run `cargo ci <command>` at any time to verify that your code hasn't introduced regressions. ## Running Locally @@ -13,82 +13,140 @@ An alias is defined in `.cargo/config.toml` at the project root: ```toml [alias] -ci = "run --manifest-path .run/Cargo.toml --bin ci --quiet --" +ci = "run --manifest-path dev/ci/Cargo.toml --bin ci --quiet --" ``` -Simply execute: +Run a single step: ```bash -cargo ci +cargo ci build-check ``` -## CI Steps +Run the full pipeline (lock → all checks → refresh → unlock) via the orchestration script: -Every CI step is an independent switch (`--check-*`). Running `cargo ci` with no options executes **all** steps in the order below; pass one or more `--check-*` flags to run only the selected steps. +```bash +python .run/src/bin/ci.py +``` + +The script is also picked up by `run.sh`: + +```bash +./run.sh ci +``` + +## Commands -| Step | Flag | What it does | -| --------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Build | `--check-build` | Recursively finds all `Cargo.toml` files and runs `cargo build` for each crate in parallel (workspace members build with all documented features). | -| Clippy | `--check-clippy` | Runs `cargo clippy ... -- -D warnings` for every crate in parallel; any warning fails the check. | -| Test | `--check-test` | Runs `cargo test` for every crate in parallel (workspace tests run with all documented features; `arg-picker` is excluded). | -| Arg picker | `--check-arg-picker` | Runs `cargo test -p arg-picker` with its default features. | -| Markdown code | `--check-markdown-code` | Runs the `test-all-markdown-code` tool to verify code blocks in all `*.md` files compile. See [ABOUT_CODE_VERIFY](docs/_ABOUT_CODE_VERIFY.md). | -| Examples | `--check-examples` | Runs the `test-examples` tool to verify all examples behave as expected. Each example declares its expected output tests in `examples/<example>/test.toml`. | -| Docs up to date | `--check-docs-refresh` | Runs the documentation refresh tools and `cargo fmt`, then fails if the working tree is no longer clean (i.e. the docs were stale). | -| API docs | `--check-api-docs` | Builds API docs with the `[package.metadata.docs.rs]` features and fails if `docs/api-docs/` is out of date. | +Every CI step is one subcommand. `cargo ci` with no subcommand prints the help page. -### Docs up to date in detail +### UTILS -`--check-docs-refresh` runs the following documentation refresh tools in sequence: +| Command | What it does | +| ---------------- | --------------------------------------------------------------------------------------- | +| `report-collect` | Assembles the collected logs in `.temp/reports/collect/` into `.temp/reports/result.md` | +| `report-clean` | Deletes all collected logs and the generated report | +| `git-lock` | Locks the workspace for a CI run (temporary commit, see below) | +| `git-unlock` | Restores the workspace and checks idempotency (see below) | +| `show-manifests` | Prints every crate path that CI will check | +| `show-features` | Prints the `docs.rs` feature list of `mingling` | -- `docs-code-box-fix` -- `docsify-sidebar-gen` -- `refresh-docs` -- `refresh-feature-mod` -- `sync-examples` +### TOOLS (refresh) -Finally, it runs `cargo fmt` to unify code formatting. Because the refresh tools regenerate derived files, running this check against stale documentation modifies the working tree — and `ci.rs` fails the run in that case. (Using `--dirty` skips the cleanliness check, which makes this flag behave like a plain "refresh docs" command.) +| Command | What it does | +| ------------------ | ---------------------------------------------------------------------- | +| `example-refresh` | Regenerates `mingling/src/example_docs.rs` and `docs/examples.json` | +| `docsify-refresh` | Fixes docsify code-box blank lines and regenerates `_sidebar.md` files | +| `features-refresh` | Regenerates `mingling/src/features.rs` from `mingling/Cargo.toml` | -### Examples in detail +These tools **write files**. Running them inside a `git-lock` / `git-unlock` pair turns them into an up-to-date check: if the generated files are stale, the tree becomes dirty and `git-unlock` fails. -`--check-examples` runs the `test-examples` tool in two phases: +### TASKS (checks) -1. **Build** — every example that has a `test.toml` is built in parallel (one `cargo build` task per example, reusing the shared `.temp/target` cache). -2. **Test** — each `[[runs]]` entry in `examples/*/test.toml` is executed serially against the pre-built binary, asserting the CLI arguments (`input`) and the expected `exit-code` / `result`. +| Command | What it does | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `build-check` | Finds all `Cargo.toml` files (minus `dev/configs/ci-ignored-dirs.txt`) and runs `cargo build` per crate in parallel. | +| `clippy-check` | Runs `cargo clippy ... -- -D warnings` for every crate in parallel; any warning fails the check. | +| `test-all` | Runs `cargo test` for every crate in parallel. Each base crate can override its command in its `mingling-ci.toml` (`[test].command`, with `<<<features>>>` expanded from the docs.rs feature list); `arg-picker` uses this to run `cargo test -p arg-picker`. | +| `example-check` | Builds every example and runs the expected-output tests declared in `examples/<example>/test.toml`. | +| `docs-check` | Builds the `mingling` API docs with the `[package.metadata.docs.rs]` features and `-D warnings`. | +| `markdown-check <PATH>` | Verifies the rust code blocks of a single markdown file compile. See [ABOUT_CODE_VERIFY](docs/_ABOUT_CODE_VERIFY.md). | +| `markdown-check-all` | Verifies all markdown files declared in `dev/configs/verified-docs.toml`. | +| `markdown-compare <A> <B>` | Compares the _structure_ of two markdown files or directories. | +| `markdown-compare-all` | Checks every translated docs directory mirrors the reference `./docs/pages/` (per `dev/configs/docs-lang.txt`). | -An example that changes its behavior only needs its own `test.toml` updated. +## Reports -### Combining steps +Every check exports its per-item outcome through the reporter into `.temp/reports/collect/`: -When several `--check-*` flags are combined, the steps run in the order listed above. In "run all" mode (no flags given), the documentation steps all execute even if one of them fails, so every problem is reported in a single run. +- `{Task}.{Platform}.ok` — one `item = location` per line (aggregated on flush). +- `{Task}.{Platform}.{item}.err` — failures, first line is the location. -## File Normalization +`cargo ci report-collect` reads that directory and renders the consolidated report (per-task tables + failure details) to `.temp/reports/result.md`: -Regardless of which steps run, `cargo ci` finishes with `git add --renormalize .` to ensure file attributes such as line endings conform to the repository configuration. +```bash +cargo ci report-collect +cat .temp/reports/result.md +``` + +`cargo ci report-clean` wipes both the collect directory and the report. ## Workspace Cleanliness and Temporary Commits -To ensure reproducible CI results, `ci.rs` imposes strict requirements on the workspace state: +To ensure reproducible CI results, CI runs inside a `git-lock` / `git-unlock` pair. + +### git-lock + +1. Pins the current HEAD to a backup branch: `git branch -f mingling/bkup HEAD` (created or force-reset). +2. If the working tree is dirty, all changes are packed into a plain temporary commit `[DO NOT PUSH] TEMP [DO NOT PUSH]`. +3. A marker file `MINGLING-CI-CHECKING` is written — content `true` when the tree was dirty, `false` when it was clean. +4. Everything is committed as `[DO NOT PUSH] CI TEMP [DO NOT PUSH]`. -- If the current workspace is not clean and `--dirty` has not been specified, the script will prompt whether to create a temporary commit: - - The commit message is `[DO NOT PUSH] CI TEMP [DO NOT PUSH]`. - - Use `-y` to auto-confirm without interaction. -- After CI finishes, the script automatically restores the workspace: - - First, `git reset --hard` discards all changes. - - If a temporary commit was created, it then runs `git reset --soft HEAD~1` and unstages everything, restoring the state to before CI started. -- If `--dirty` is specified, the temporary commit and the final cleanliness check are skipped. +``` +clean: A ── CI TEMP (marker = false) +dirty: A ── TEMP (your changes) ── CI TEMP (marker = true) +``` + +### git-unlock + +Only acts when the HEAD commit message contains `CI TEMP` (case-sensitive); otherwise it refuses with a non-zero exit. The restore path is picked by the marker: + +- `true` — hard reset past the marker commit, then soft reset + unstage, so **your pre-lock changes are restored into the working tree**. +- `false` — a single hard reset back to the original HEAD. + +If the working tree is dirty when unlocking (e.g. CI left tracked changes behind, such as stale generated docs), the restore still runs but the command reports a **non-zero exit code** — this is the idempotency check. In CI, that fails the job. The dirtiness check compares **content**, not file timestamps, so merely touching files during a build never fails the check. + +Pass `--show-diff` to print the diff of those tracked changes before they are discarded: + +```bash +cargo ci git-unlock --show-diff +``` + +This is what the CI workflow uses: an idempotency failure shows exactly what contaminated the workspace in the job logs. -> **Warning**: `git reset --hard` is executed at the end of CI. If you use `--dirty`, ensure you have no unsaved important changes. +> **Warning**: when unlocking a `true` lock, changes made _during_ CI are discarded. Anything you had before locking comes back. ## GitHub Actions Workflow `.github/workflows/ci.yml` defines the project's CI: - Triggered on `push` to the `main` branch. -- A single `Check` job runs every `--check-*` step in a **step × platform** matrix (`ubuntu-latest` and `windows-latest`), i.e. `cargo ci --check-<item>` for each combination. The `.temp` build cache is no longer used; every matrix job starts from a clean workspace. +- A `Check` job runs in a **item × platform** matrix (`ubuntu-latest`, `windows-latest`, `macos-latest`), each combination being `cargo ci <command>` inside a `git-lock` / `git-unlock` pair: + +| Matrix item | Command | +| --------------- | ------------------------------------------------------------------- | +| `build` | `cargo ci build-check` | +| `clippy` | `cargo ci clippy-check` | +| `test` | `cargo ci test-all` | +| `arg-picker` | `cargo ci test-all` (covered via its `mingling-ci.toml` override) | +| `markdown-code` | `cargo ci markdown-check-all && cargo ci markdown-compare-all` | +| `examples` | `cargo ci example-check` | +| `docs-refresh` | `cargo ci example-refresh` + `docsify-refresh` + `features-refresh` | +| `api-docs` | `cargo ci docs-check` | + +- Every matrix job uploads its `.temp/reports/collect/` as an artifact — **even on failure**, so failures are always collected. +- A `Report` job (runs even when some checks failed) downloads all collect artifacts, runs `cargo ci report-collect`, and publishes `result.md` to the job summary via `$GITHUB_STEP_SUMMARY`. - After CI passes, the `unreleased` tag is automatically moved to the latest commit on `main`. -For non-`main` branches and pull requests, `.github/workflows/ci-check-only.yml` runs the same matrix without moving the tag or deploying. +For non-`main` branches and pull requests, `.github/workflows/ci-check-only.yml` runs the same matrix and report collection without moving the tag or deploying. ### API Documentation Deployment diff --git a/docs/dev/pages/abouts/code-verify-system.md b/docs/dev/pages/abouts/code-verify-system.md index 929b337..f52052f 100644 --- a/docs/dev/pages/abouts/code-verify-system.md +++ b/docs/dev/pages/abouts/code-verify-system.md @@ -7,16 +7,28 @@ This system automatically extracts and compiles Rust code blocks from docs, ensu ## 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. +Specify which Markdown files to verify via `dev/configs/verified-docs.toml`: -You can also test a single file via command-line arg: +```toml +[verified] +readme = "./README.md" +getting_started = "./GETTING-STARTED.md" +documents_en_us = "./docs/pages/**" +documents_zh_cn = "./docs/_zh_CN/pages/**" +``` + +Each key is a label used to name the report items; values are single files, directories, or `**` globs. + +Run all configured files: ```sh -./run-tools.sh test-all-markdown-code docs/pages/1-getting-started.md +cargo ci markdown-check-all ``` -```powershell -.\run-tools.ps1 test-all-markdown-code docs/pages/1-getting-started.md +You can also test a single file via command-line arg (path is joined onto the current directory): + +```sh +cargo ci markdown-check docs/pages/1-getting-started.md ``` ## Default Rules @@ -74,7 +86,7 @@ After the **default rules** are applied, each block goes through: ### 2. Temp Project Generation -Each block (or each dedup-hash group) gets its own Cargo project: +Each dedup-hash group gets its own Cargo project: ``` .temp/doc-test/<hash>/ @@ -85,18 +97,16 @@ Each block (or each dedup-hash group) gets its own Cargo project: ### 3. Build Verification -Compiled with `cargo build --release`, stderr inherited to the terminal for real-time progress. +Compiled with `cargo check --manifest-path ... --color=always`, stderr inherited to the terminal for real-time progress. Blocks within a group are serial (they share the crate directory); groups run in parallel. - **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: +Each file's result is exported through the reporter: an `ok` entry when every block passed, otherwise an `err` entry carrying the failed blocks' details. All entries land in `.temp/reports/collect/` (e.g. `Markdown-Check-All.Linux.ok`, `Markdown-Check-All.Linux.<item>.err`). -- Total tests, passed, failed -- Table of results per block (block #, file, line, status) -- Detailed errors for failed blocks +`cargo ci report-collect` then assembles everything into `.temp/reports/result.md` (also published to the GitHub Actions job summary). ### 5. Exit Code @@ -121,12 +131,15 @@ 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`. +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`. The declared features are mirrored into `[build-dependencies]` so `build.rs` sees the same feature set. ```rust // BUILD TIME -// Features: ["builds", "pathf"] -analyze_and_build_type_mapping().unwrap(); +// Dependencies: +// serde = "1" +fn main() { + // build-time work, e.g. writing generated sources into OUT_DIR +} ``` ### `// Features: [...]` @@ -197,13 +210,18 @@ Use `@@@` for: ## 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 | +| Module | Responsibility | +| ----------------------------------------- | ------------------------------------------------------------------------------------ | +| `dev/ci/src/markdown/project.rs` | Block parsing, Cargo.toml/main.rs generation, FNV-1a dep hash | +| `dev/ci/src/markdown/test.rs` | Grouping by dep hash, parallel `cargo check` execution | +| `dev/ci/src/task/cmd_markdown_check.rs` | `markdown-check` / `markdown-check-all` commands: read config, collect files, report | +| `dev/ci/src/markdown/compare.rs` | Structural signature comparison (for `markdown-compare`) | +| `dev/ci/src/task/cmd_markdown_compare.rs` | `markdown-compare` / `markdown-compare-all` commands | +| `dev/configs/verified-docs.toml` | Specifies which doc files to verify | ---- +### Structure Comparison + +`markdown-compare` (two files or directories) and `markdown-compare-all` (all languages from `dev/configs/docs-lang.txt`, whose first line is the reference directory) check that every translated docs directory **mirrors the structure** of the reference docs exactly: one token per line classifying headings, fenced code blocks (with language tag), `@@@` lines, blank lines, blockquotes, lists and plain text. Translated text may differ; the structure may not. ## Full Example diff --git a/docs/example-viewer.html b/docs/example-viewer.html index 0417c30..77232ec 100644 --- a/docs/example-viewer.html +++ b/docs/example-viewer.html @@ -450,7 +450,7 @@ Mìng Lìng </a> <div class="nav-links"> - <a href="doc.html">Docs</a> + <a href="index.html">Docs</a> <a href="examples.html">Examples</a> <a href="https://github.com/mingling-rs/mingling" @@ -553,7 +553,7 @@ exampleName; // ── Load file list from auto-generated JSON ── - fetch("example-pages/examples.json") + fetch("examples.json") .then(function (r) { if (!r.ok) throw new Error("HTTP " + r.status); return r.json(); diff --git a/docs/examples.html b/docs/examples.html index 9d2ae8c..4ea41e8 100644 --- a/docs/examples.html +++ b/docs/examples.html @@ -426,7 +426,7 @@ Mìng Lìng </a> <div class="nav-links"> - <a href="doc.html">Docs</a> + <a href="index.html">Docs</a> <a href="examples.html" class="active">Examples</a> <a href="https://github.com/mingling-rs/mingling" @@ -476,7 +476,7 @@ // ── Load examples from auto-generated JSON ── var examples = []; - fetch("example-pages/examples.json") + fetch("examples.json") .then(function (r) { if (!r.ok) throw new Error("HTTP " + r.status); return r.json(); diff --git a/docs/example-pages/examples.json b/docs/examples.json index 38f73cd..dd5b65b 100644 --- a/docs/example-pages/examples.json +++ b/docs/examples.json @@ -69,13 +69,11 @@ "tags": [ "pathf", "dispatch_tree", - "extras", - "build.rs" + "extras" ], "files": [ "src/main.rs", "src/sub/mod.rs", - "build.rs", "Cargo.toml" ] }, @@ -87,13 +85,11 @@ "desc": "Combines the `pathf` feature with entry metadata. The metadata `DataType` and the entry `BindType` are defined inside a submodule, and `pathf` resolves them for `gen_program!()` at build time.\n", "tags": [ "pathf", - "metadata", - "build.rs" + "metadata" ], "files": [ "src/main.rs", "src/sub/mod.rs", - "build.rs", "Cargo.toml" ] }, @@ -124,7 +120,6 @@ ], "files": [ "src/main.rs", - "build.rs", "Cargo.toml" ] }, @@ -294,12 +289,10 @@ "desc": "Demonstrates the `pathf` feature, which automatically resolves type module paths at build time. Types can be defined in submodules without explicit `use` in the main module.\n", "tags": [ "pathf", - "build.rs", "architecture" ], "files": [ "Cargo.toml", - "build.rs", "src/main.rs", "src/sub/mod.rs" ] diff --git a/docs/doc.html b/docs/index.html index a63fdd3..a63fdd3 100644 --- a/docs/doc.html +++ b/docs/index.html diff --git a/docs/LICENSE b/docs/licenses/docsify.md index bec4d76..bec4d76 100644 --- a/docs/LICENSE +++ b/docs/licenses/docsify.md diff --git a/docs/pages/12-exit-code.md b/docs/pages/12-exit-code.md index 8fa320c..e9ad9de 100644 --- a/docs/pages/12-exit-code.md +++ b/docs/pages/12-exit-code.md @@ -12,7 +12,7 @@ Providing the shell with a correct exit code when a program terminates is a basi @@@use mingling::setup::ExitCodeSetup; fn main() { let mut program = ThisProgram::new(); - program.with_setup(ExitCodeSetup::default()); + program.with_setup(ExitCodeSetup); @@@ program.exec_and_exit(); } ``` @@ -55,7 +55,7 @@ fn handle_check(_args: EntryCheck, ec: &mut ResExitCode) { @@@use mingling::setup::ExitCodeSetup; fn main() { let mut program = ThisProgram::new(); - program.with_setup(ExitCodeSetup::default()); + program.with_setup(ExitCodeSetup); // Get exit code and handle it yourself let exit_code = program.exec(); diff --git a/docs/pages/advanced/1-completion.md b/docs/pages/advanced/1-completion.md index 55b8b1d..ca1f621 100644 --- a/docs/pages/advanced/1-completion.md +++ b/docs/pages/advanced/1-completion.md @@ -11,13 +11,6 @@ Mingling's completion is **fully dynamic** — no static completion files, sugge # Cargo.toml [dependencies.mingling] features = ["comp"] - -[build-dependencies.mingling] -features = [ - "comp", - # Enable `build` for build-time support - "build" -] ``` ## How it works @@ -43,7 +36,7 @@ Use `#[completion(EntryType)]` to define completion logic for an Entry: @@@dispatcher!("greet", EntryGreet); #[completion(EntryGreet)] -fn complete_greet(ctx: &ShellContext) -> Suggest { +fn complete_greet(ctx: ShellContext) -> Suggest { if ctx.previous_word == "greet" { let mut items = BTreeSet::new(); items.insert(SuggestItem::new_with_desc("Alice".into(), "Likes to receive messages".into())); @@ -72,8 +65,18 @@ suggest! { ## Generate completion scripts -Call `build_comp_scripts` in `build.rs` to generate completion scripts (requires `builds` + `comp` features). +When the `comp` feature is enabled, `gen_program!()` automatically invokes `build_comp!()` at compile time, which generates the completion scripts (named after `CARGO_PKG_NAME`) into `target/mingling/`. + +If your binary name differs from the crate name, call `build_comp!()` manually with the binary name: +```rust +// Features: ["comp"] +@@@use mingling::macros::build_comp; +@@@fn example() { +build_comp!("mybin"); +@@@} +``` + See [example-completion](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-completion). <p align="center" style="font-size: 0.85em; color: gray;"> diff --git a/docs/pages/other/features.md b/docs/pages/other/features.md index b2c0ea5..858e556 100644 --- a/docs/pages/other/features.md +++ b/docs/pages/other/features.md @@ -25,42 +25,6 @@ Mingling provides a set of **preset feature groups** that make it easy to enable **Positioning:** Full mode, enables all of Mingling's core functionality. In addition to `advanced`, it includes clap integration, the full structural renderer (with all serialization formats), and the experimental path analyzer. Suitable for large, feature-complete command-line applications. -## `build_advanced` - -**Enables features:** `build`, `comp` - -**Positioning:** Build-time enhanced configuration, used to generate build helpers such as completion scripts at build time (the `comp` feature provides completion script generation). - -> [!NOTE] -> -> This feature group is intended for **build dependencies** only and must be used alongside the `advanced` feature. Enable it in the `[build-dependencies]` section of `Cargo.toml`: - -```toml -[dependencies.mingling] -features = ["advanced"] - -[build-dependencies.mingling] -features = ["build_advanced"] -``` - -## `build_full` - -**Enables features:** `build`, `comp`, `pathf`, `dispatch_tree` - -**Positioning:** Full build-time configuration, extends `build_advanced` with the path analyzer (`pathf`) to automatically resolve type module paths, suitable for projects with complex structures that require automated build-time analysis. - -> [!NOTE] -> -> This feature group is intended for **build dependencies** only and must be used alongside the `full` feature. Enable it in the `[build-dependencies]` section of `Cargo.toml`: - -```toml -[dependencies.mingling] -features = ["full"] - -[build-dependencies.mingling] -features = ["build_full"] -``` - # Feature Details ## Feature `all_serde_fmt` @@ -91,23 +55,6 @@ async fn handle_state_foo(foo: StateFoo) -> Next { 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 -// BUILD TIME -// Features: ["builds", "comp"] -use mingling::build::build_comp_scripts; - -// Generate completion scripts for `myprogram` -build_comp_scripts("myprogram").unwrap(); -``` - ## Feature `clap` **Description:** @@ -318,17 +265,10 @@ When enabled, types can be defined in any submodule, and `gen_program!()` can au # Cargo.toml [dependencies.mingling] features = ["pathf"] - -[build-dependencies.mingling] -features = ["builds", "pathf"] -``` - -```rust -// BUILD TIME -// Features: ["pathf"] -analyze_and_build_type_mapping().unwrap(); ``` +With the `pathf` feature enabled, `gen_program!()` automatically invokes `build_pathf!()` at compile time to run the type mapping analysis. + See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-pathfinder) ## Feature `picker` |