[pull] main from SandAI-org:main

.github/workflows/check_chinese_chars.py

@@ -42,6 +42,8 @@
     "]"
 )
 
+EXEMPT_DOCUMENT_NAMES: List[str] = ["docs/README_zh.md"]
+
 BINARY_EXTENSIONS = frozenset(
     {
         ".png",
@@ -130,7 +132,12 @@ def _check_diff(base_sha: str, head_sha: str) -> List[Tuple[str, int, str]]:
         if line.startswith("+"):
             line_num += 1
             content = line[1:]
-            if current_file and not _is_binary(current_file) and CHINESE_CHAR_PATTERN.search(content):
+            if (
+                current_file
+                and current_file not in EXEMPT_DOCUMENT_NAMES
+                and not _is_binary(current_file)
+                and CHINESE_CHAR_PATTERN.search(content)
+            ):
                 findings.append((current_file, line_num, content))
         elif not line.startswith("-"):
             line_num += 1
@@ -150,7 +157,7 @@ def _check_all_files() -> List[Tuple[str, int, str]]:
 
     findings: List[Tuple[str, int, str]] = []
     for filepath in tracked:
-        if not filepath or _is_binary(filepath) or not os.path.isfile(filepath):
+        if not filepath or filepath in EXEMPT_DOCUMENT_NAMES or _is_binary(filepath) or not os.path.isfile(filepath):
             continue
         try:
             with open(filepath, encoding="utf-8", errors="ignore") as fh:

.github/workflows/sphinx.yaml

@@ -0,0 +1,38 @@
+name: sphinx deploy
+
+on:
+    push:
+        branches:
+        -   main
+permissions:
+    contents: write
+jobs:
+    deploy:
+        runs-on: ubuntu-latest
+        steps:
+        -   uses: actions/checkout@v4
+        -   name: Set up Python
+            uses: actions/setup-python@v5
+            with:
+                python-version: '3.12'
+        -   name: Install dependencies
+            run: |
+                sudo apt-get update
+                sudo apt-get install -y rsync
+                cd docs
+                pip install -r requirements.txt
+        -   name: Build docs
+            run: |
+                cd docs
+                make clean
+                # English at root (backward-compatible URLs)
+                DOCS_LANGUAGE=en sphinx-build -b html source/ build/html/
+                # Chinese under zh_CN/
+                DOCS_LANGUAGE=zh_CN sphinx-build -b html source/ build/html/zh_CN/
+        -   name: Deploy to GitHub Pages
+            uses: JamesIves/github-pages-deploy-action@v4
+            if: ${{ github.event_name == 'push' }}
+            with:
+                branch: gh-pages
+                folder: docs/build/html
+                target-folder: docs/main

.gitignore

@@ -79,6 +79,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/build/
 
 # PyBuilder
 .pybuilder/

docs/Makefile

@@ -0,0 +1,42 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+LOCALEDIR     = locale
+GETTEXTDIR    = $(BUILDDIR)/gettext
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+.PHONY: gettext update-po html-en html-zh html-multilang
+
+gettext:
+	@$(SPHINXBUILD) -M gettext "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+update-po: gettext
+	@sphinx-intl update -p "$(GETTEXTDIR)" -d "$(LOCALEDIR)" -l zh_CN
+
+# Multi-language docs layout: English lives at the site root ($(BUILDDIR)/html/),
+# Chinese lives under $(BUILDDIR)/html/zh_CN/. This keeps single- and
+# multi-language builds consistent with the language switcher and the CI deploy
+# layout ("English at root, Chinese under zh_CN/").
+html-en:
+	@DOCS_LANGUAGE=en $(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
+html-zh:
+	@DOCS_LANGUAGE=zh_CN $(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html/zh_CN" $(SPHINXOPTS) $(O)
+
+html-multilang: html-en html-zh
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,119 @@
+Chinese version: [`README_zh.md`](./README_zh.md)
+
+# MagiCompiler Documentation Guide
+
+This guide explains how to build, preview, and contribute to the MagiCompiler documentation. No prior Sphinx experience is required.
+
+## Prerequisites
+
+- Python 3.10+
+- `pip` (comes with Python)
+- A terminal (bash, zsh, PowerShell, etc.)
+- A text editor (VS Code, Vim, etc.)
+
+## Quick Start (5 minutes)
+
+```bash
+# 1. Enter the docs directory
+cd docs
+
+# 2. Install dependencies (one-time)
+pip install -r requirements.txt
+
+# 3. Build the docs
+make html
+
+# 4. Open in browser
+open build/html/index.html        # macOS
+xdg-open build/html/index.html    # Linux
+start build/html/index.html       # Windows (Git Bash)
+```
+
+That's it! You should see the documentation in your browser.
+
+> **Tip:** Run `make clean && make html` to force a full rebuild if you see stale content.
+
+---
+
+## Directory Structure
+
+```
+docs/
+├── source/                  # All documentation source files live here
+│   ├── index.md             # Homepage
+│   ├── conf.py              # Sphinx configuration (rarely need to edit)
+│   ├── _static/             # Custom CSS, images referenced by docs
+│   ├── _templates/          # HTML templates (e.g. language switcher)
+│   ├── user_guide/          # User-facing guides
+│   │   ├── toc.md           # Table of contents for user guide section
+│   │   ├── install.md       # Installation guide
+│   │   └── quickstart.md    # Quick start guide
+│   └── blog/                # Technical blog posts
+│       ├── toc.md           # Table of contents for blog section
+│       └── refs/            # BibTeX citation files (one per blog post)
+├── locale/                  # Chinese translation files (.po)
+│   └── zh_CN/LC_MESSAGES/
+├── build/                   # Generated output (git-ignored)
+├── requirements.txt         # Python dependencies
+├── Makefile                 # Build commands (Linux/macOS)
+└── make.bat                 # Build commands (Windows)
+```
+
+---
+
+## Build Commands
+
+| Command | Description |
+|---------|-------------|
+| `make html` | Build the English docs (default) |
+| `make html-en` | Build the English docs into `build/html` (site root) |
+| `make html-zh` | Build the Chinese docs into `build/html/zh_CN` |
+| `make html-multilang` | Build both English and Chinese docs |
+| `make update-po` | Regenerate `.po` translation templates |
+| `make clean` | Remove the `build/` directory |
+
+---
+
+## How to Write Documentation
+
+All documentation is written in **Markdown** using [MyST syntax](https://myst-parser.readthedocs.io/en/latest/), which extends standard Markdown with Sphinx-specific features.
+
+### Adding a New User Guide Page
+
+1. Create a new `.md` file in `source/user_guide/`.
+2. Register its filename (without `.md`) in `source/user_guide/toc.md`.
+3. Build and preview with `make clean && make html`.
+
+### Adding a New Blog Post
+
+1. Create `source/blog/my_topic.md` with a YAML frontmatter header
+   (`blogpost: true`, `date`, `author`, ...).
+2. If it has citations, create `source/blog/refs/my_topic.bib` and add the
+   title to the `blog_titles` list in `source/conf.py`.
+3. Register it in `source/blog/toc.md`.
+4. Build and preview.
+
+---
+
+## Bilingual Docs (English + Chinese)
+
+All documentation uses **English as the single source of truth**. Chinese
+translations are managed via `.po` files following the standard Sphinx
+internationalization (i18n) workflow.
+
+```
+source/*.md (English source, "single source of truth")
+     │
+     ▼  make update-po
+locale/zh_CN/LC_MESSAGES/*.po (Chinese translations)
+     │
+     ▼  make html-multilang
+build/html/        (English site, at the site root)
+build/html/zh_CN/  (Chinese site, with a language switcher)
+```
+
+1. Edit the English `.md` sources under `source/` as usual.
+2. Run `make update-po` to extract/refresh translation strings.
+3. Translate the `msgstr` entries in `locale/zh_CN/LC_MESSAGES/*.po`
+   (leave the `msgid` untouched).
+4. Run `make html-multilang` to build both languages.

docs/README_zh.md

@@ -0,0 +1,117 @@
+英文版本请见：[`README.md`](./README.md)
+
+# MagiCompiler 文档指南
+
+本指南说明如何构建、预览和贡献 MagiCompiler 文档。无需任何 Sphinx 经验即可上手。
+
+## 前置条件
+
+- Python 3.10+
+- `pip`（Python 自带）
+- 终端（bash、zsh、PowerShell 等均可）
+- 文本编辑器（VS Code、Vim 等均可）
+
+## 快速上手（5 分钟）
+
+```bash
+# 1. 进入 docs 目录
+cd docs
+
+# 2. 安装依赖（仅首次需要）
+pip install -r requirements.txt
+
+# 3. 构建文档
+make html
+
+# 4. 在浏览器中打开
+open build/html/index.html        # macOS
+xdg-open build/html/index.html    # Linux
+start build/html/index.html       # Windows (Git Bash)
+```
+
+完成！你应该能在浏览器中看到文档了。
+
+> **提示：** 如果看到旧内容，运行 `make clean && make html` 强制全量重建。
+
+---
+
+## 目录结构
+
+```
+docs/
+├── source/                  # 所有文档源文件都在这里
+│   ├── index.md             # 首页
+│   ├── conf.py              # Sphinx 配置文件（一般不需要改）
+│   ├── _static/             # 自定义 CSS、文档引用的图片
+│   ├── _templates/          # HTML 模板（如语言切换器）
+│   ├── user_guide/          # 面向用户的指南
+│   │   ├── toc.md           # 用户指南章节的目录
+│   │   ├── install.md       # 安装指南
+│   │   └── quickstart.md    # 快速开始
+│   └── blog/                # 技术博客文章
+│       ├── toc.md           # 博客章节的目录
+│       └── refs/            # BibTeX 引用文件（每篇博客一个）
+├── locale/                  # 中文翻译文件（.po）
+│   └── zh_CN/LC_MESSAGES/
+├── build/                   # 生成的输出（已被 git 忽略）
+├── requirements.txt         # Python 依赖
+├── Makefile                 # 构建命令（Linux/macOS）
+└── make.bat                 # 构建命令（Windows）
+```
+
+---
+
+## 构建命令
+
+| 命令 | 说明 |
+|------|------|
+| `make html` | 构建英文文档（默认） |
+| `make html-en` | 构建英文文档到 `build/html`（站点根目录） |
+| `make html-zh` | 构建中文文档到 `build/html/zh_CN` |
+| `make html-multilang` | 同时构建英文和中文文档 |
+| `make update-po` | 重新生成 `.po` 翻译模板 |
+| `make clean` | 删除 `build/` 目录 |
+
+---
+
+## 如何编写文档
+
+所有文档都使用 **Markdown** 编写，采用 [MyST 语法](https://myst-parser.readthedocs.io/en/latest/)——它在标准 Markdown 基础上扩展了 Sphinx 特有的功能。
+
+### 新增一篇用户指南
+
+1. 在 `source/user_guide/` 下创建一个新的 `.md` 文件。
+2. 在 `source/user_guide/toc.md` 中注册其文件名（不含 `.md`）。
+3. 用 `make clean && make html` 构建并预览。
+
+### 新增一篇博客文章
+
+1. 创建带 YAML frontmatter 头部（`blogpost: true`、`date`、`author` 等）的
+   `source/blog/my_topic.md`。
+2. 如果包含引用文献，创建 `source/blog/refs/my_topic.bib`，并在
+   `source/conf.py` 的 `blog_titles` 列表中添加该标题。
+3. 在 `source/blog/toc.md` 中注册。
+4. 构建并预览。
+
+---
+
+## 中英文双语文档
+
+所有文档以**英文为主源**，中文翻译通过 `.po` 文件管理，遵循标准的 Sphinx 国际化（i18n）工作流。
+
+```
+source/*.md（英文源文件，"唯一真相源"）
+     │
+     ▼  make update-po
+locale/zh_CN/LC_MESSAGES/*.po（中文翻译）
+     │
+     ▼  make html-multilang
+build/html/        （英文站点，位于站点根目录）
+build/html/zh_CN/  （中文站点，带语言切换器）
+```
+
+1. 照常编辑 `source/` 下的英文 `.md` 源文件。
+2. 运行 `make update-po` 提取/刷新翻译字符串。
+3. 在 `locale/zh_CN/LC_MESSAGES/*.po` 中翻译 `msgstr` 条目
+   （不要修改 `msgid`）。
+4. 运行 `make html-multilang` 同时构建两种语言。