From 6be5894f40b2c2543f23aab7f7b4ffc73dbd0d77 Mon Sep 17 00:00:00 2001 From: 魏曹先生 <1992414357@qq.com> Date: Fri, 10 Jul 2026 18:17:39 +0800 Subject: docs: migrate ABOUT-CI and ABOUT-NIGHTLY to dev docs site Replace relative file links with absolute URLs and add centered page headers to the migrated docs. Update the dev sidebar to include the new pages. --- ABOUT-CI.md | 68 ----------------------------- ABOUT-NIGHTLY.md | 15 ------- CONTRIBUTING.md | 2 +- docs/dev/_sidebar.md | 2 + docs/dev/pages/abouts/ci.md | 71 +++++++++++++++++++++++++++++++ docs/dev/pages/abouts/nightly-features.md | 18 ++++++++ 6 files changed, 92 insertions(+), 84 deletions(-) delete mode 100644 ABOUT-CI.md delete mode 100644 ABOUT-NIGHTLY.md create mode 100644 docs/dev/pages/abouts/ci.md create mode 100644 docs/dev/pages/abouts/nightly-features.md diff --git a/ABOUT-CI.md b/ABOUT-CI.md deleted file mode 100644 index 4cbcd6f..0000000 --- a/ABOUT-CI.md +++ /dev/null @@ -1,68 +0,0 @@ -# About Mingling CI Process - -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. - -During development, you can run `cargo ci` at any time to verify that your code hasn't introduced regressions. - -## Running Locally - -An alias is defined in `.cargo/config.toml` at the project root: - -```toml -[alias] -ci = "run --manifest-path .run/Cargo.toml --bin ci --quiet --" -``` - -Simply execute: - -```bash -cargo ci -``` - -## CI Execution Flow - -`cargo ci` runs the following stages in order: - -### 1. Code Checking Stage (run by default, or individually via `--test-codes`) - -- **Scan and build all crates**: Recursively finds all `Cargo.toml` files in the project and runs `cargo build` for each crate in parallel. -- **Run Clippy on all crates**: Executes `cargo clippy ... -- -D warnings` in parallel; any warning will cause a failure. -- **Run unit tests for all crates**: Executes `cargo test` in parallel. - -### 2. Documentation and Example Checking Stage (run by default, or individually via `--test-docs`) - -- **Test all examples**: Runs the `test-examples` tool. -- **Verify Markdown code blocks compile**: Runs the `test-all-markdown-code` tool to check code blocks in all `*.md` files. See [ABOUT_CODE_VERIFY](docs/_ABOUT_CODE_VERIFY.md) for details. -- **Check if documentation is up to date**: Runs the following documentation refresh tools in sequence: - - `docs-code-box-fix` - - `docsify-sidebar-gen` - - `refresh-docs` - - `refresh-feature-mod` - - `sync-examples` -- Finally, runs `cargo fmt` to unify code formatting. - -### 3. File Normalization - -Runs `git add --renormalize .` to ensure file attributes such as line endings conform to the repository configuration. - -## Workspace Cleanliness and Temporary Commits - -To ensure reproducible CI results, `ci.rs` imposes strict requirements on the workspace state: - -- 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. - -> **Warning**: `git reset --hard` is executed at the end of CI. If you use `--dirty`, ensure you have no unsaved important changes. - -## GitHub Actions Workflow - -`.github/workflows/ci.yml` defines the project's CI: - -- Triggered on `push` to the `main` branch. -- Runs `cargo ci` in parallel on `ubuntu-latest` and `windows-latest`. -- After CI passes, the `unreleased` tag is automatically moved to the latest commit on `main`. diff --git a/ABOUT-NIGHTLY.md b/ABOUT-NIGHTLY.md deleted file mode 100644 index f2d4ec7..0000000 --- a/ABOUT-NIGHTLY.md +++ /dev/null @@ -1,15 +0,0 @@ -# About Nightly Rust - -**Mingling** uses some features that are only available in the `nightly` toolchain. This requires you to enable the `nightly` feature: - -```toml -[dependencies] -mingling = { version = "...", features = ["nightly"] } -``` - -## Features - -> [!WARNING] -> The following features can only be used with the nightly toolchain, and are only guaranteed to compile, not to be stable or production-ready. -> -> If you need a stable development experience, please **do not use** the `nightly` feature! diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e8e4bed..ffb0064 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,7 +70,7 @@ After editing documentation, refresh relevant files: These steps are included in `cargo ci`; running `cargo ci` will execute them automatically. > [!TIP] -> You can check the [ABOUT CI](./ABOUT-CI.md) section to learn how "Mingling CI" works. +> You can check the [ABOUT CI](https://mingling-rs.github.io/mingling/docs/dev/#/pages/abouts/ci) section to learn how "Mingling CI" works. ## 4. Regarding AI Agent Usage diff --git a/docs/dev/_sidebar.md b/docs/dev/_sidebar.md index 5182676..e303735 100644 --- a/docs/dev/_sidebar.md +++ b/docs/dev/_sidebar.md @@ -5,6 +5,8 @@ * [Some Situations Where You'd Be Like "Shit!"](pages/issues/the-shit-time) * 💡 Abouts * [AI Translation Rule](pages/abouts/ai-translation-rule) + * [About Mingling CI Process](pages/abouts/ci) * [Markdown Code Verification System](pages/abouts/code-verify-system) + * [About Nightly Features](pages/abouts/nightly-features) * 📄 Templates * [Helpdoc Template](pages/templates/doc) diff --git a/docs/dev/pages/abouts/ci.md b/docs/dev/pages/abouts/ci.md new file mode 100644 index 0000000..3a93c1c --- /dev/null +++ b/docs/dev/pages/abouts/ci.md @@ -0,0 +1,71 @@ +

About Mingling CI Process

+

+ CI workflow and local execution guide for Mingling +

+ +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. + +During development, you can run `cargo ci` at any time to verify that your code hasn't introduced regressions. + +## Running Locally + +An alias is defined in `.cargo/config.toml` at the project root: + +```toml +[alias] +ci = "run --manifest-path .run/Cargo.toml --bin ci --quiet --" +``` + +Simply execute: + +```bash +cargo ci +``` + +## CI Execution Flow + +`cargo ci` runs the following stages in order: + +### 1. Code Checking Stage (run by default, or individually via `--test-codes`) + +- **Scan and build all crates**: Recursively finds all `Cargo.toml` files in the project and runs `cargo build` for each crate in parallel. +- **Run Clippy on all crates**: Executes `cargo clippy ... -- -D warnings` in parallel; any warning will cause a failure. +- **Run unit tests for all crates**: Executes `cargo test` in parallel. + +### 2. Documentation and Example Checking Stage (run by default, or individually via `--test-docs`) + +- **Test all examples**: Runs the `test-examples` tool. +- **Verify Markdown code blocks compile**: Runs the `test-all-markdown-code` tool to check code blocks in all `*.md` files. See [ABOUT_CODE_VERIFY](docs/_ABOUT_CODE_VERIFY.md) for details. +- **Check if documentation is up to date**: Runs the following documentation refresh tools in sequence: + - `docs-code-box-fix` + - `docsify-sidebar-gen` + - `refresh-docs` + - `refresh-feature-mod` + - `sync-examples` +- Finally, runs `cargo fmt` to unify code formatting. + +### 3. File Normalization + +Runs `git add --renormalize .` to ensure file attributes such as line endings conform to the repository configuration. + +## Workspace Cleanliness and Temporary Commits + +To ensure reproducible CI results, `ci.rs` imposes strict requirements on the workspace state: + +- 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. + +> **Warning**: `git reset --hard` is executed at the end of CI. If you use `--dirty`, ensure you have no unsaved important changes. + +## GitHub Actions Workflow + +`.github/workflows/ci.yml` defines the project's CI: + +- Triggered on `push` to the `main` branch. +- Runs `cargo ci` in parallel on `ubuntu-latest` and `windows-latest`. +- After CI passes, the `unreleased` tag is automatically moved to the latest commit on `main`. diff --git a/docs/dev/pages/abouts/nightly-features.md b/docs/dev/pages/abouts/nightly-features.md new file mode 100644 index 0000000..13b666e --- /dev/null +++ b/docs/dev/pages/abouts/nightly-features.md @@ -0,0 +1,18 @@ +

About Nightly Features

+

+ Using nightly Rust features in Mingling +

+ +**Mingling** uses some features that are only available in the `nightly` toolchain. This requires you to enable the `nightly` feature: + +```toml +[dependencies] +mingling = { version = "...", features = ["nightly"] } +``` + +## Features + +> [!WARNING] +> The following features can only be used with the nightly toolchain, and are only guaranteed to compile, not to be stable or production-ready. +> +> If you need a stable development experience, please **do not use** the `nightly` feature! -- cgit