aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
author魏曹先生 <1992414357@qq.com>2026-08-19 05:54:00 +0800
committer魏曹先生 <1992414357@qq.com>2026-08-19 06:15:20 +0800
commitec9edc294fd5e7e29977fc7b0e6fb953422bc0e2 (patch)
treebbf89ef4457b8de8a8a9bca5668045d612d27572 /docs
parent06dfc27194c11e1d1033c292c759a1c5d82e780b (diff)
chore: reorganize dev tools into dev/ directory and consolidate configsHEADmain
Move CI, dev tools, and configs from root-level scattered locations into a unified `dev/` directory structure. Update all references across build scripts, documentation, and editor configurations. Also consolidate editor config generation into build.rs for automated synchronization of rust-analyzer settings across VS Code and Zed.
Diffstat (limited to 'docs')
-rw-r--r--docs/_zh_CN/index.html2
-rw-r--r--docs/dev/README.md2
-rw-r--r--docs/dev/index.html2
-rw-r--r--docs/dev/pages/abouts/ci.md72
-rw-r--r--docs/dev/pages/abouts/code-verify-system.md20
-rw-r--r--docs/example-viewer.html4
-rw-r--r--docs/examples.html4
-rw-r--r--docs/examples.json (renamed from docs/example-pages/examples.json)0
-rw-r--r--docs/index.html (renamed from docs/doc.html)0
-rw-r--r--docs/licenses/docsify.md (renamed from docs/LICENSE)0
10 files changed, 53 insertions, 53 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/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 f9a58be..37015eb 100644
--- a/docs/dev/pages/abouts/ci.md
+++ b/docs/dev/pages/abouts/ci.md
@@ -3,7 +3,7 @@
CI workflow and local execution guide for Mingling
</p>
-Mingling's CI process is built into the project itself: the execution logic lives in `mingling_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.
+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 <command>` at any time to verify that your code hasn't introduced regressions.
@@ -13,7 +13,7 @@ An alias is defined in `.cargo/config.toml` at the project root:
```toml
[alias]
-ci = "run --manifest-path mingling_ci/Cargo.toml --bin ci --quiet --"
+ci = "run --manifest-path dev/ci/Cargo.toml --bin ci --quiet --"
```
Run a single step:
@@ -40,38 +40,38 @@ Every CI step is one subcommand. `cargo ci` with no subcommand prints the help p
### UTILS
-| Command | What it does |
-| --------------- | ----------------------------------------------------------------------- |
+| 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` |
+| `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` |
### TOOLS (refresh)
-| Command | What it does |
-| ------------------- | --------------------------------------------------------------------------------- |
-| `example-refresh` | Regenerates `mingling/src/example_docs.rs` and `docs/example-pages/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` |
+| 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` |
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.
### TASKS (checks)
-| Command | What it does |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `build-check` | Finds all `Cargo.toml` files (minus `.config/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 `.config/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 `.config/docs-lang.txt`). |
+| 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`). |
## Reports
@@ -122,7 +122,7 @@ 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**: when unlocking a `true` lock, changes made *during* CI are discarded. Anything you had before locking comes back.
+> **Warning**: when unlocking a `true` lock, changes made _during_ CI are discarded. Anything you had before locking comes back.
## GitHub Actions Workflow
@@ -131,16 +131,16 @@ This is what the CI workflow uses: an idempotency failure shows exactly what con
- Triggered on `push` to the `main` branch.
- 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` |
+| 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`.
diff --git a/docs/dev/pages/abouts/code-verify-system.md b/docs/dev/pages/abouts/code-verify-system.md
index c2a9215..f52052f 100644
--- a/docs/dev/pages/abouts/code-verify-system.md
+++ b/docs/dev/pages/abouts/code-verify-system.md
@@ -7,7 +7,7 @@ This system automatically extracts and compiles Rust code blocks from docs, ensu
## Config
-Specify which Markdown files to verify via `.config/verified-docs.toml`:
+Specify which Markdown files to verify via `dev/configs/verified-docs.toml`:
```toml
[verified]
@@ -210,18 +210,18 @@ Use `@@@` for:
## Structure Overview
-| Module | Responsibility |
-| --------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `mingling_ci/src/markdown/project.rs` | Block parsing, Cargo.toml/main.rs generation, FNV-1a dep hash |
-| `mingling_ci/src/markdown/test.rs` | Grouping by dep hash, parallel `cargo check` execution |
-| `mingling_ci/src/task/cmd_markdown_check.rs` | `markdown-check` / `markdown-check-all` commands: read config, collect files, report |
-| `mingling_ci/src/markdown/compare.rs` | Structural signature comparison (for `markdown-compare`) |
-| `mingling_ci/src/task/cmd_markdown_compare.rs`| `markdown-compare` / `markdown-compare-all` commands |
-| `.config/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 `.config/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.
+`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 dd5b65b..dd5b65b 100644
--- a/docs/example-pages/examples.json
+++ b/docs/examples.json
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