Skip to content

Commit 773cfe8

Browse files
Charliechen114514Charliechen114514
authored
periodic: merge to main as stable (#3)
* feat: wallpaper settings; config manager enhanced * feat: add filesystem filter issue * update the project ci * feat: migrate to vitepress * feat: minimize the pre-push issue * doc: sync docs
1 parent a3e526e commit 773cfe8

446 files changed

Lines changed: 25958 additions & 27826 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/cpp-check.yml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
name: C++ Check
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- main
7+
- release/*
8+
types:
9+
- opened
10+
- synchronize
11+
- reopened
12+
workflow_dispatch:
13+
14+
permissions:
15+
contents: read
16+
17+
jobs:
18+
linux-build-test:
19+
name: Linux build and tests
20+
runs-on: ubuntu-latest
21+
22+
steps:
23+
- name: Checkout
24+
uses: actions/checkout@v4
25+
26+
- name: Build Docker image
27+
run: |
28+
docker build \
29+
--platform linux/amd64 \
30+
--build-arg QT_ARCH=linux_gcc_64 \
31+
-f scripts/docker/Dockerfile.build \
32+
-t cfdesktop-build \
33+
.
34+
35+
- name: Configure, build, and test
36+
run: |
37+
docker run --rm \
38+
--platform linux/amd64 \
39+
-e QT_QPA_PLATFORM=offscreen \
40+
-v "$PWD:/project" \
41+
-w /project \
42+
cfdesktop-build \
43+
bash -lc "bash scripts/build_helpers/linux_develop_build.sh ci -c build_ci_config.ini && bash scripts/build_helpers/linux_run_tests.sh ci -c build_ci_config.ini"
44+
45+
docs-build:
46+
name: VitePress docs build
47+
runs-on: ubuntu-latest
48+
49+
steps:
50+
- name: Checkout
51+
uses: actions/checkout@v4
52+
53+
- name: Setup pnpm
54+
uses: pnpm/action-setup@v4
55+
with:
56+
version: 10.33.3
57+
58+
- name: Setup Node.js
59+
uses: actions/setup-node@v4
60+
with:
61+
node-version: 24
62+
cache: pnpm
63+
64+
- name: Install dependencies
65+
run: pnpm install --frozen-lockfile
66+
67+
- name: Build docs
68+
run: pnpm build

‎.github/workflows/deploy.yml‎

Lines changed: 41 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -1,94 +1,61 @@
1-
# 工作流名称
2-
name: 自动部署 MkDocs
1+
name: Deploy VitePress
32

4-
# 触发条件：推送到 main 分支
53
on:
64
push:
75
branches:
86
- main
9-
10-
# 允许手动触发
117
workflow_dispatch:
128

13-
# 设置权限
149
permissions:
15-
contents: write # 允许推送到 gh-pages 分支
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: pages
16+
cancel-in-progress: false
1617

1718
jobs:
18-
deploy:
19+
build:
1920
runs-on: ubuntu-latest
20-
21+
2122
steps:
22-
# 1. 检出代码
23-
- name: 检出仓库
23+
- name: Checkout
2424
uses: actions/checkout@v4
25+
26+
- name: Setup pnpm
27+
uses: pnpm/action-setup@v4
2528
with:
26-
fetch-depth: 0 # 获取完整历史，显示文章修改时间
27-
28-
# 2. 设置 Python
29-
- name: 设置 Python
30-
uses: actions/setup-python@v5
31-
with:
32-
python-version: "3.11"
33-
# cache: 'pip' # 缓存依赖，加速构建
34-
35-
# 3. 安装依赖
36-
- name: 安装依赖
37-
run: |
38-
pip install mkdocs-material
39-
pip install mkdocs-awesome-pages-plugin
40-
pip install mkdocs-git-revision-date-localized-plugin
41-
42-
# 4. 安装 Doxygen
43-
- name: 安装 Doxygen
44-
run: |
45-
sudo apt-get update
46-
sudo apt-get install -y doxygen
29+
version: 10.33.3
4730

48-
# 5. 安装 doxybook2
49-
- name: 安装 doxybook2
50-
run: |
51-
# 下载最新版本的 doxybook2
52-
DOXYBOOK2_VERSION="1.5.0"
53-
wget https://github.com/matusnovak/doxybook2/releases/download/v${DOXYBOOK2_VERSION}/doxybook2-linux-amd64-v${DOXYBOOK2_VERSION}.zip
54-
unzip doxybook2-linux-amd64-v${DOXYBOOK2_VERSION}.zip
55-
sudo mv bin/doxybook2 /usr/local/bin/
56-
sudo chmod +x /usr/local/bin/doxybook2
57-
doxybook2 --version
31+
- name: Setup Node.js
32+
uses: actions/setup-node@v4
33+
with:
34+
node-version: 24
35+
cache: pnpm
5836

59-
# 6. 生成 API 文档(Doxygen → Markdown)
60-
- name: 生成 API 文档
61-
run: |
62-
doxygen Doxyfile
63-
rm -rf document/api
64-
mkdir -p document/api
65-
doxybook2 --input ./xml \
66-
--output ./document/api \
67-
--config doxybook.json
37+
- name: Setup Pages
38+
uses: actions/configure-pages@v5
6839

69-
# 6.5. 为自动生成的 API 文档配置导航
70-
- name: 配置 API 导航
71-
run: |
72-
cat > document/api/.pages <<'EOF'
73-
title: API 自动文档
74-
icon: material/file-document
75-
nav:
76-
- 命名空间: Namespaces
77-
- 类: Classes
78-
- 文件: Files
79-
EOF
40+
- name: Install dependencies
41+
run: pnpm install --frozen-lockfile
8042

81-
# 6.6. 修复 doxybook2 生成的相对链接路径
82-
- name: 修复 API 文档链接
83-
run: python3 scripts/document/fix_doxybook_links.py
43+
- name: Build docs
44+
run: pnpm build
8445

85-
# 7. 构建网站
86-
- name: 构建网站
87-
run: mkdocs build --clean
88-
89-
# 8. 自动部署到 gh-pages 分支（这一步会自动触发 GitHub Pages）
90-
- name: 部署到 GitHub Pages
91-
uses: peaceiris/actions-gh-pages@v4
46+
- name: Upload artifact
47+
uses: actions/upload-pages-artifact@v3
9248
with:
93-
github_token: ${{ secrets.GITHUB_TOKEN }} # GitHub 自动提供的 token
94-
publish_dir: ./site # MkDocs 构建输出目录
49+
path: site/.vitepress/dist
50+
51+
deploy:
52+
environment:
53+
name: github-pages
54+
url: ${{ steps.deployment.outputs.page_url }}
55+
needs: build
56+
runs-on: ubuntu-latest
57+
58+
steps:
59+
- name: Deploy to GitHub Pages
60+
id: deployment
61+
uses: actions/deploy-pages@v4

‎.github/workflows/docs-check.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: Docs Check
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- develop
7+
types:
8+
- opened
9+
- synchronize
10+
- reopened
11+
- labeled
12+
13+
permissions:
14+
contents: read
15+
16+
jobs:
17+
vitepress:
18+
name: VitePress build
19+
if: contains(github.event.pull_request.labels.*.name, 'build-doc')
20+
runs-on: ubuntu-latest
21+
22+
steps:
23+
- name: Checkout
24+
uses: actions/checkout@v4
25+
26+
- name: Setup pnpm
27+
uses: pnpm/action-setup@v4
28+
with:
29+
version: 10.33.3
30+
31+
- name: Setup Node.js
32+
uses: actions/setup-node@v4
33+
with:
34+
node-version: 24
35+
cache: pnpm
36+
37+
- name: Install dependencies
38+
run: pnpm install --frozen-lockfile
39+
40+
- name: Build docs
41+
run: pnpm build

‎.gitignore‎

Lines changed: 38 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,38 @@
1-
# ignores
2-
.cache
3-
.claude
4-
5-
# aqtinstall log
6-
aqtinstall.log
7-
# privates
8-
BLUEPRINT.md
9-
10-
# native builds
11-
out/
12-
13-
# Documents summons
14-
xml/
15-
site/
16-
document/api/
17-
18-
# .vscode
19-
.vscode
20-
21-
# third_party dependencies (downloaded during configuration)
22-
third_party/*/
23-
!third_party/.gitkeep
24-
25-
__pycache__/
26-
27-
# Python virtual environment
28-
.venv/
29-
30-
# Docker build logs
31-
scripts/docker/logger/
1+
# ignores
2+
.cache
3+
.claude
4+
CLAUDE.md
5+
MEMORY.md
6+
7+
# aqtinstall log
8+
aqtinstall.log
9+
# privates
10+
BLUEPRINT.md
11+
12+
# native builds
13+
out/
14+
15+
# Documents summons
16+
xml/
17+
document/api/
18+
19+
# .vscode
20+
.vscode
21+
22+
# third_party dependencies (downloaded during configuration)
23+
third_party/*/
24+
!third_party/.gitkeep
25+
26+
__pycache__/
27+
28+
# Python virtual environment
29+
.venv/
30+
31+
# Docker build logs
32+
scripts/docker/logger/
33+
34+
# Node/VitePress
35+
node_modules/
36+
site/.vitepress/cache/
37+
site/.vitepress/dist/
38+
site/.vitepress/.temp

‎AGENT.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# AGENT.md — Project Conventions for AI Agents
2+
3+
## Build System
4+
5+
- **Language**: C++23 / CMake (minimum 3.16), Qt 6
6+
- **Build directory**: `out/build_develop/`
7+
- **Configure**: `bash scripts/build_helpers/linux_configure.sh`
8+
- **Build (no re-configure)**: `bash scripts/build_helpers/linux_fast_develop_build.sh`
9+
- **Build (full clean + build + tests)**: `bash scripts/build_helpers/linux_develop_build.sh`
10+
11+
## Doxygen Fix Workflow
12+
13+
### 1. Read the spec
14+
15+
Read `document/DOXYGEN_REQUEST.md` in full — it is the authoritative Doxygen style guide.
16+
17+
### 2. Read the violations
18+
19+
Read `FAILED_DOXYGEN.md` for the current list of violations, grouped by file.
20+
21+
### 3. Read the linter
22+
23+
Skim `scripts/doxygen/lint.py` to understand the exact checks (file header, function blocks, return tags, param directions, language rules, etc.).
24+
25+
### 4. Fix by file
26+
27+
For each flagged file, read the source, then:
28+
29+
1. **File header** — add `/** @file ... */` at top if missing (see DOXYGEN_REQUEST.md Section 2).
30+
2. **Type comments** — add `/** @brief ... */` before any undocumented public enum/struct/class.
31+
3. **Function comments** — add a Doxygen block before each flagged function. Key rules:
32+
- Every `@param` needs a direction: `[in]`, `[out]`, or `[in,out]`.
33+
- Non-void functions **must** have `@return`. Void functions **must not**.
34+
- Tags to always include: `@brief`, `@throws` (or `None`), `@note` (or `None`), `@warning` (or `None`), `@since` (`N/A`), `@ingroup` (`none`).
35+
4. **Style consistency** — use `/** */` block style or `///` line style consistently within a file.
36+
5. **Language** — third-person present tense only. No "will", "we", "I", "our", "my".
37+
38+
### 5. Validate
39+
40+
```bash
41+
python3 scripts/doxygen/lint.py
42+
```
43+
44+
Iterate up to 3 passes if violations remain.
45+
46+
## Key Constraints
47+
48+
- Only edit Doxygen comments — never change code logic.
49+
- All comments in English.
50+
- Comment lines must be ≤ 100 characters.
51+
- When uncertain about behavior, use `@note FIXME: ...` rather than guessing.

0 commit comments

Comments
 (0)