From 8f388d4a9e05a2e278defb535e805c08ad859a97 Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Tue, 3 Feb 2026 08:15:59 +0800
Subject: [PATCH] =?UTF-8?q?docs(ci):=20=E6=B7=BB=E5=8A=A0=E6=96=87?=
=?UTF-8?q?=E6=A1=A3=E7=94=9F=E6=88=90=E9=85=8D=E7=BD=AE=E5=92=8C=E8=87=AA?=
=?UTF-8?q?=E5=8A=A8=E5=8C=96=E5=8F=91=E5=B8=83=E6=B5=81=E7=A8=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- 新增 docfx.json 配置文件用于 API 文档生成
- 在所有项目文件中启用 GenerateDocumentationFile 选项
- 添加 GitHub Actions 工作流 publish-docs.yml 实现文档自动发布
- 配置工作流触发条件支持标签推送和特定提交信息
- 设置文档构建环境使用 .NET 10.0 和 DocFX 工具
- 实现文档站点部署到 GitHub Pages 的完整流程
- [release doc]
---
.github/workflows/publish-docs.yml | 93 +++++++++++++++++++
.../GFramework.Core.Abstractions.csproj | 1 +
GFramework.Core/GFramework.Core.csproj | 1 +
.../GFramework.Game.Abstractions.csproj | 1 +
GFramework.Game/GFramework.Game.csproj | 1 +
GFramework.Godot/GFramework.Godot.csproj | 1 +
docfx.json | 19 ++++
7 files changed, 117 insertions(+)
create mode 100644 .github/workflows/publish-docs.yml
create mode 100644 docfx.json
diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
new file mode 100644
index 0000000..bd439ad
--- /dev/null
+++ b/.github/workflows/publish-docs.yml
@@ -0,0 +1,93 @@
+# 工作流名称：Publish Docs
+# 该工作流用于在推送到 main 分支时自动构建并发布文档到 GitHub Pages。
+
+name: Publish Docs
+
+# 触发条件：
+# 定义工作流的触发规则。当代码仓库发生特定事件时，将自动执行相关操作。
+# 此处配置表示：当向仓库推送（push）带有标签（tag）的提交时触发工作流。
+# 标签匹配规则为通配符 '*'，即任意标签都会触发。
+on:
+ push:
+ branches:
+ - '**'
+ tags:
+ - '*'
+
+# 权限配置：指定工作流所需的权限。
+# actions: read - 允许读取 GitHub Actions 相关信息。
+# pages: write - 允许写入 GitHub Pages 内容。
+# id-token: write - 允许写入身份令牌（用于部署认证）。
+permissions:
+ actions: read
+ pages: write
+ id-token: write
+
+# 并发控制：确保同一组任务不会同时运行。
+# group: "pages" - 将并发任务分组为 "pages"。
+# cancel-in-progress: false - 不取消正在进行的任务。
+concurrency:
+ group: "pages"
+ cancel-in-progress: false
+
+# 定义工作流中的作业。
+# if 条件表达式用于判断是否执行该作业。
+# 表达式逻辑如下：
+# 1. startsWith(github.ref, 'refs/tags/')：检查当前引用是否以 'refs/tags/' 开头，即是否为标签推送。
+# 2. contains(github.event.head_commit.message, '[release doc]')：检查提交信息中是否包含 '[release doc]' 字符串。
+# 若任一条件满足，则执行该作业。
+jobs:
+ if: |
+ startsWith(github.ref, 'refs/tags/')
+ || contains(github.event.head_commit.message, '[release doc]')
+
+ # 作业名称：publish-docs，负责构建和发布文档。
+ publish-docs:
+ # 运行环境：使用最新版本的 Ubuntu 虚拟机。
+ runs-on: ubuntu-latest
+
+ # 环境配置：指定部署的目标环境为 github-pages，并设置页面 URL。
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+
+ # 步骤定义：按顺序执行一系列操作以完成文档构建与发布。
+ steps:
+ # 步骤 1：检出代码仓库。
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ # 步骤 2：安装 .NET SDK。
+ - name: Setup .NET
+ uses: actions/setup-dotnet@v4
+ with:
+ dotnet-version: 10.0.x
+
+ # 步骤 3：恢复项目依赖项。
+ - name: Restore
+ run: dotnet restore
+
+ # 步骤 4：构建项目并生成 XML 文档。
+ - name: Build (generate XML docs)
+ run: dotnet build -c Release
+
+ # 步骤 5：安装 DocFX 工具。
+ - name: Install DocFX
+ run: dotnet tool update -g docfx
+
+ # 步骤 6：使用 DocFX 构建静态站点。
+ - name: Build DocFX
+ run: |
+ export PATH="$PATH:$HOME/.dotnet/tools"
+ docfx docfx/docfx.json
+
+ # 步骤 7：上传构建好的静态站点文件作为工件。
+ - name: Upload Pages Artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: docfx/_site
+
+ # 步骤 8：将静态站点部署到 GitHub Pages。
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
diff --git a/GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj b/GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj
index 59b201f..b3fcc67 100644
--- a/GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj
+++ b/GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj
@@ -9,6 +9,7 @@
true
T:System.Diagnostics.CodeAnalysis.NotNullWhenAttribute
enable
+ true
diff --git a/GFramework.Core/GFramework.Core.csproj b/GFramework.Core/GFramework.Core.csproj
index a4d0adf..2775e88 100644
--- a/GFramework.Core/GFramework.Core.csproj
+++ b/GFramework.Core/GFramework.Core.csproj
@@ -5,6 +5,7 @@
net8.0;net9.0;net10.0
disable
enable
+ true
diff --git a/GFramework.Game.Abstractions/GFramework.Game.Abstractions.csproj b/GFramework.Game.Abstractions/GFramework.Game.Abstractions.csproj
index 931805c..8390835 100644
--- a/GFramework.Game.Abstractions/GFramework.Game.Abstractions.csproj
+++ b/GFramework.Game.Abstractions/GFramework.Game.Abstractions.csproj
@@ -9,6 +9,7 @@
true
T:System.Diagnostics.CodeAnalysis.NotNullWhenAttribute
enable
+ true
diff --git a/GFramework.Game/GFramework.Game.csproj b/GFramework.Game/GFramework.Game.csproj
index 799cbae..e7a6d25 100644
--- a/GFramework.Game/GFramework.Game.csproj
+++ b/GFramework.Game/GFramework.Game.csproj
@@ -5,6 +5,7 @@
net8.0;net9.0;net10.0
disable
enable
+ true
diff --git a/GFramework.Godot/GFramework.Godot.csproj b/GFramework.Godot/GFramework.Godot.csproj
index c28514a..afa4775 100644
--- a/GFramework.Godot/GFramework.Godot.csproj
+++ b/GFramework.Godot/GFramework.Godot.csproj
@@ -5,6 +5,7 @@
disable
enable
net8.0;net9.0;net10.0
+ true
diff --git a/docfx.json b/docfx.json
new file mode 100644
index 0000000..0d2a294
--- /dev/null
+++ b/docfx.json
@@ -0,0 +1,19 @@
+{
+ "metadata": [
+ {
+ "src": [
+ {
+ "files": [ "GFramework.sln" ]
+ }
+ ],
+ "dest": "api"
+ }
+ ],
+ "build": {
+ "content": [
+ { "files": [ "api/**.yml", "api/index.md" ] },
+ { "files": [ "docs/**.md", "docs/**/toc.yml" ] }
+ ],
+ "dest": "_site"
+ }
+}