diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_ABOUT_CODE_VERIFY.md | 195 | ||||
| -rw-r--r-- | docs/_ABOUT_TRANSLATION.md (renamed from docs/TRANSLATION_RULE.md) | 8 | ||||
| -rw-r--r-- | docs/_DOCS_TEMPLATE.md (renamed from docs/TEMPLATE.md) | 7 |
3 files changed, 205 insertions, 5 deletions
diff --git a/docs/_ABOUT_CODE_VERIFY.md b/docs/_ABOUT_CODE_VERIFY.md new file mode 100644 index 0000000..e28f59d --- /dev/null +++ b/docs/_ABOUT_CODE_VERIFY.md @@ -0,0 +1,195 @@ +# 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/<hash>/ +├── 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() {} +``` + +### `// 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. + +--- + +## 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/TRANSLATION_RULE.md b/docs/_ABOUT_TRANSLATION.md index 9c77faa..cc33128 100644 --- a/docs/TRANSLATION_RULE.md +++ b/docs/_ABOUT_TRANSLATION.md @@ -1,14 +1,17 @@ # 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. + +- **缩写** (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): @@ -17,5 +20,6 @@ - **最小化改动** (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/TEMPLATE.md b/docs/_DOCS_TEMPLATE.md index 047d92b..6a56bbd 100644 --- a/docs/TEMPLATE.md +++ b/docs/_DOCS_TEMPLATE.md @@ -5,10 +5,11 @@ Content here -<iframe +<!-- To display playable code if needed --> +<!--<iframe src="../play/play.html?tur=default.md&title=Title" - height="600px"/> - + height="600px"/>--> + <p align="center" style="font-size: 0.85em; color: gray;"> Written by @Your-Name </p> |