feat(docs): add Makefile build flow and update docs

* ✨ feat(docs): 更新文档以支持 Makefile 构建流程 - 添加 Makefile 文件以简化开发环境设置 - 更新 README 和中文文档，说明使用 `make` 命令进行依赖安装和启动开发环境 - 更新快速开始文档，增加 Makefile 相关说明 * ✨ feat(docs): 更新文档以支持 Makefile 构建流程和快速检查命令 * ✨ feat(docs): 更新文档以说明如何贡献官网内容和预览文档
2026-06-27 23:52:54 +08:00 · 2026-06-27 23:52:54 +08:00 · c925f9a9de
parent 350d2a3533
commit c925f9a9de
8 changed files with 159 additions and 37 deletions
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@ -23,11 +23,10 @@

 <!-- 说明如何验证你的改动，例如：命令、测试用例、手动操作步骤 -->

- [ ] `pnpm check` 通过
- [ ] `cargo check --no-default-features` 通过
+- [ ] `make check` 通过
+- [ ] `make cargo-check-fast` 通过
 - [ ] 相关测试通过

 ## 关联 Issue

 <!-- 如有，填写 `Close #xxx` 或 `Related #xxx` -->
-
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -19,25 +19,33 @@ Required tools:

 - Node.js `>=22.13.0`
 - pnpm `10.27.0`
+- Make
 - Rust stable
 - Java 17, when working on JDBC plugin packaging

 Install dependencies:

 ```bash
-pnpm install
+make install
 ```

 Run the desktop app during development:

 ```bash
-pnpm dev:tauri
+make
 ```

-Run the web backend:
+Run the web app during development:

 ```bash
-pnpm dev:backend
+make dev-web       # frontend
+make dev-backend   # backend
+```
+
+Preview the documentation site:
+
+```bash
+make docs
 ```

 ## Checks
@ -45,7 +53,7 @@ pnpm dev:backend
 Before opening a pull request, run:

 ```bash
-pnpm check
+make check
 cargo fmt --check
 cargo check --workspace --locked
 ```
@ -55,9 +63,9 @@ cargo check --workspace --locked
 > development when you're not touching DuckDB features:
 >
 > ```bash
-> cargo check --workspace --no-default-features
-> cargo test  --workspace --no-default-features
-> pnpm tauri dev -- --no-default-features
+> make cargo-check-fast
+> make cargo-test-fast
+> make dev-fast
 > ```
 >
 > Release builds and CI should always include DuckDB (omit the flag).
--- a/90
+++ b/90
@ -0,0 +1,90 @@
+.DEFAULT_GOAL := dev
+
+PNPM ?= pnpm
+TAURI_DEV_PORT ?= 1420
+
+.PHONY: help install docs-install check-tauri-dev-port dev dev-fast dev-web dev-backend build package docs docs-build check test cargo-check-fast cargo-test-fast
+
+node_modules/.modules.yaml: package.json pnpm-lock.yaml
+	$(PNPM) install --frozen-lockfile
+
+docs/node_modules/.modules.yaml: docs/package.json docs/pnpm-lock.yaml
+	cd docs && $(PNPM) install --frozen-lockfile --ignore-workspace
+
+help:
+	@printf '%s\n' 'DBX development targets:'
+	@printf '%s\n' ''
+	@printf '%s\n' 'App:'
+	@printf '  %-23s %s\n' 'make' 'Start the local desktop development environment'
+	@printf '  %-23s %s\n' 'make dev' 'Start the local desktop development environment'
+	@printf '  %-23s %s\n' 'make dev-fast' 'Start Tauri dev without default Rust features'
+	@printf '  %-23s %s\n' 'make dev-web' 'Start the web frontend development server'
+	@printf '  %-23s %s\n' 'make dev-backend' 'Start the web backend development server'
+	@printf '  %-23s %s\n' 'make build' 'Run type checks and build the desktop frontend'
+	@printf '  %-23s %s\n' 'make package' 'Build the desktop app package'
+	@printf '%s\n' ''
+	@printf '%s\n' 'Docs:'
+	@printf '  %-23s %s\n' 'make docs' 'Start the documentation site development server'
+	@printf '  %-23s %s\n' 'make docs-build' 'Build the documentation site'
+	@printf '  %-23s %s\n' 'make docs-install' 'Install documentation site dependencies'
+	@printf '%s\n' ''
+	@printf '%s\n' 'Checks:'
+	@printf '  %-23s %s\n' 'make check' 'Run project checks'
+	@printf '  %-23s %s\n' 'make test' 'Run project tests'
+	@printf '  %-23s %s\n' 'make cargo-check-fast' 'Run Rust check without default features'
+	@printf '  %-23s %s\n' 'make cargo-test-fast' 'Run Rust tests without default features'
+	@printf '%s\n' ''
+	@printf '%s\n' 'Setup:'
+	@printf '  %-23s %s\n' 'make install' 'Install root project dependencies'
+
+install:
+	$(PNPM) install --frozen-lockfile
+
+docs-install:
+	cd docs && $(PNPM) install --frozen-lockfile --ignore-workspace
+
+check-tauri-dev-port:
+	@if lsof -nP -iTCP:$(TAURI_DEV_PORT) -sTCP:LISTEN >/dev/null 2>&1; then \
+		echo "Port $(TAURI_DEV_PORT) is already in use. DBX Tauri dev requires http://localhost:$(TAURI_DEV_PORT)."; \
+		echo ""; \
+		lsof -nP -iTCP:$(TAURI_DEV_PORT) -sTCP:LISTEN; \
+		echo ""; \
+		echo "Stop the process above, then run make dev again. Example: kill <PID>"; \
+		exit 1; \
+	fi
+
+dev: node_modules/.modules.yaml check-tauri-dev-port
+	$(PNPM) dev:tauri
+
+dev-fast: node_modules/.modules.yaml check-tauri-dev-port
+	$(PNPM) tauri dev -- --no-default-features
+
+dev-web: node_modules/.modules.yaml
+	$(PNPM) dev:web
+
+dev-backend: node_modules/.modules.yaml
+	$(PNPM) dev:backend
+
+build: node_modules/.modules.yaml
+	$(PNPM) build:checked
+
+package: node_modules/.modules.yaml
+	$(PNPM) tauri build
+
+docs: docs/node_modules/.modules.yaml
+	cd docs && ./node_modules/.bin/next dev --hostname 127.0.0.1
+
+docs-build: docs/node_modules/.modules.yaml
+	cd docs && ./node_modules/.bin/next build && node scripts/generate-sitemap.mjs
+
+check: node_modules/.modules.yaml
+	$(PNPM) check
+
+test: node_modules/.modules.yaml
+	$(PNPM) test
+
+cargo-check-fast:
+	cargo check --no-default-features
+
+cargo-test-fast:
+	cargo test --no-default-features
--- a/README.md
+++ b/README.md
@ -246,21 +246,22 @@ No additional dependencies required.
 ### Development

 ```bash
-pnpm install
-pnpm dev:tauri
+make
 ```

+`make` installs root dependencies when needed and starts the local Tauri desktop development environment.
+
 > [!TIP]
 > DuckDB compilation takes a while. If you're not working on DuckDB features,
 > skip it to speed up local builds:
 >
 > ```bash
 > # Fast checks (skip DuckDB)
-> cargo check --no-default-features
-> cargo test  --no-default-features
+> make cargo-check-fast
+> make cargo-test-fast
 >
 > # Tauri dev without DuckDB
-> pnpm tauri dev -- --no-default-features
+> make dev-fast
 > ```
 >
 > The `--no-default-features` flag only affects local development.
@ -269,10 +270,18 @@ pnpm dev:tauri
 Web version:

 ```bash
-pnpm dev:web       # frontend
-pnpm dev:backend   # backend
+make dev-web       # frontend
+make dev-backend   # backend
 ```

+Documentation site:
+
+```bash
+make docs
+```
+
+The official DBX documentation site lives in `docs/`. If you want to improve the website content or documentation pages, edit the files under `docs/` and run `make docs` to preview the site locally.
+
 JDBC agent driver development projects live in `agents/`:

 ```bash
@ -285,7 +294,7 @@ Build artifacts from `agents/drivers/<db-type>/build/libs/` are picked up by loc
 ### Build

 ```bash
-pnpm tauri build
+make package
 ```

 The installer will be in `src-tauri/target/release/bundle/`.
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@ -247,20 +247,21 @@ sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libappindicator3-dev
 ### 开发

 ```bash
-pnpm install
-pnpm dev:tauri
+make
 ```

+`make` 会在需要时安装根目录依赖，并启动本地 Tauri 桌面端开发环境。
+
 > [!TIP]
 > DuckDB 从源码编译较慢。如果不涉及 DuckDB 功能，可以跳过以加速本地构建：
 >
 > ```bash
 > # 快速检查（跳过 DuckDB）
-> cargo check --no-default-features
-> cargo test  --no-default-features
+> make cargo-check-fast
+> make cargo-test-fast
 >
 > # Tauri 开发模式跳过 DuckDB
-> pnpm tauri dev -- --no-default-features
+> make dev-fast
 > ```
 >
 > `--no-default-features` 仅影响本地开发，发布构建（`pnpm tauri build`）始终包含 DuckDB。
@ -268,10 +269,18 @@ pnpm dev:tauri
 Web 版本：

 ```bash
-pnpm dev:web       # 前端
-pnpm dev:backend   # 后端
+make dev-web       # 前端
+make dev-backend   # 后端
 ```

+文档站：
+
+```bash
+make docs
+```
+
+DBX 官网文档位于 `docs/` 目录。如果你想贡献官网内容或文档页面，请修改 `docs/` 下的文件，并运行 `make docs` 在本地预览文档站。
+
 JDBC Agent 驱动开发工程位于 `agents/` 目录：

 ```bash
@ -284,7 +293,7 @@ cd agents
 ### 构建

 ```bash
-pnpm tauri build
+make package
 ```

 安装包输出在 `src-tauri/target/release/bundle/` 目录。
--- a/docs/content/docs/getting-started.cn.mdx
+++ b/docs/content/docs/getting-started.cn.mdx
@ -183,6 +183,7 @@ description: 安装 DBX、创建第一个连接，并了解桌面版、Docker

 - [Node.js](https://nodejs.org/) >= 18
 - [pnpm](https://pnpm.io/)
+- Make
 - [Rust](https://www.rust-lang.org/tools/install) >= 1.77

 ### 系统依赖
@ -198,21 +199,22 @@ description: 安装 DBX、创建第一个连接，并了解桌面版、Docker
 ```bash
 git clone https://github.com/t8y2/dbx.git
 cd dbx
-pnpm install
-pnpm dev:tauri
+make
 ```

+`make` 会在需要时安装根目录依赖，并启动本地 Tauri 桌面端开发环境。
+
 Web 版本：

 ```bash
-pnpm dev:web
-pnpm dev:backend
+make dev-web
+make dev-backend
 ```

 ### 构建桌面安装包

 ```bash
-pnpm tauri build
+make package
 ```

 桌面安装包会输出到 `src-tauri/target/release/bundle/`。
--- a/docs/content/docs/getting-started.mdx
+++ b/docs/content/docs/getting-started.mdx
@ -183,6 +183,7 @@ Use source mode when contributing or debugging DBX locally.

 - [Node.js](https://nodejs.org/) >= 18
 - [pnpm](https://pnpm.io/)
+- Make
 - [Rust](https://www.rust-lang.org/tools/install) >= 1.77

 ### System Dependencies
@ -198,21 +199,22 @@ Use source mode when contributing or debugging DBX locally.
 ```bash
 git clone https://github.com/t8y2/dbx.git
 cd dbx
-pnpm install
-pnpm dev:tauri
+make
 ```

+`make` installs root dependencies when needed and starts the local Tauri desktop development environment.
+
 For the web version:

 ```bash
-pnpm dev:web
-pnpm dev:backend
+make dev-web
+make dev-backend
 ```

 ### Build Desktop Packages

 ```bash
-pnpm tauri build
+make package
 ```

 Desktop installers are written to `src-tauri/target/release/bundle/`.
--- a/docs/pnpm-workspace.yaml
+++ b/docs/pnpm-workspace.yaml
@ -0,0 +1,3 @@
+allowBuilds:
+  esbuild: true
+  sharp: true