aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/_zh_CN/index.html2
-rw-r--r--docs/dev/_sidebar.md2
-rw-r--r--docs/dev/index.html2
-rw-r--r--docs/dev/pages/abouts/ci.md71
-rw-r--r--docs/dev/pages/abouts/nightly-features.md18
-rw-r--r--docs/doc.html2
6 files changed, 94 insertions, 3 deletions
diff --git a/docs/_zh_CN/index.html b/docs/_zh_CN/index.html
index 7adaa98..ad21062 100644
--- a/docs/_zh_CN/index.html
+++ b/docs/_zh_CN/index.html
@@ -56,7 +56,7 @@
auto2top: true,
loadSidebar: true,
maxLevel: 0,
- subMaxLevel: 3,
+ subMaxLevel: 0,
search: {
placeholder: "Search",
noData: "No matches found.",
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/index.html b/docs/dev/index.html
index e62268d..1bfb5c5 100644
--- a/docs/dev/index.html
+++ b/docs/dev/index.html
@@ -141,7 +141,7 @@
auto2top: true,
loadSidebar: true,
maxLevel: 0,
- subMaxLevel: 3,
+ subMaxLevel: 0,
search: {
placeholder: "Search dev docs…",
noData: "No matches found.",
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 @@
+<h1 align="center">About Mingling CI Process</h1>
+<p align="center">
+ 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.
+
+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 @@
+<h1 align="center">About Nightly Features</h1>
+<p align="center">
+ Using nightly Rust features in Mingling
+</p>
+
+**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/docs/doc.html b/docs/doc.html
index 783ccb4..a63fdd3 100644
--- a/docs/doc.html
+++ b/docs/doc.html
@@ -51,7 +51,7 @@
auto2top: true,
loadSidebar: true,
maxLevel: 0,
- subMaxLevel: 3,
+ subMaxLevel: 0,
search: {
placeholder: "Search",
noData: "No matches found.",