Unity 项目文档生成

Unity 项目文档生成

对于 C# 项目来说,可以使用 docfx 这个开源工具来生成代码文档,这个工具也同样能用在 Unity 的项目中。

以我的 KimerA 框架的项目结构为例吧:

1
2
3
4
5
6
7
KimerA
├─Docs
└─Src
├─KimerA
│ ├─.vscode
│ ├─Assets
......

其中 KimerA/Src/KimerA 就是 unity 项目的根目录。

首先保证至少有 DotNet8 的环境

运行 dotnet tool update -g docfx 来全局安装 docfx 工具

关于 docfx 的入门,建议直接看官方的 https://dotnet.github.io/docfx/index.html

KimerA/Docs 打开一个终端,输入 docfx init 初始化相关设置

然后应该就看到了 Docs 文件夹下多了 docfx.json, index.md, toc.yml 这三个文件

启动 docfx 服务后的主界面就是根据 index.md 来的

toc.yml (Table of Config),就和名字一样,是指示文档结构的

docfx.json 就是生成文档时的相关配置

docfx.json 中 metadata -> src 应该默认是指向一个 .csproj 路径,但是对于 unity 项目,建议改成 .cs 文件的路径

下面是一个示例的 docfx.json 文件内容,(当然,由于我是为了打包成 unitypackage 我才放到 Plugins 下面,如果只是要给项目核心逻辑的哪些脚本生成文档,大可改成类似 TestProj/Assets/Scripts/*.cs , TestProj/Assets/Scripts/**/*.cs 这样的)

需要解释一下为什么在 metadata 中会添加一个 "references": [ "*.dll" ]

因为我依赖了 UnityEngine,所以当 docfx 尝试 build 的时候(生成文档前会先build)就会缺少依赖,我的做法是直接去编辑器文件夹下面复制了一个 UnityEngine.dll (不知道有没有更好的办法)

然后 “references” 字段需要的是模式,可以填 “UnityEngine.dll”, “*.dll”,但是不能 “./UnityEngine.dll”

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
{
"metadata": [
{
"src": [
{
"files": [
"KimerA/Assets/Plugins/KimerA/Runtime/**/*.cs"
],
"src": "../Src"
}
],
"dest": "api",
"disableGitFeatures": false,
"disableDefaultFilter": false,
"references": [
"*.dll"
]
}
],
"build": {
"globalMetadata": {
"_disableContribution": true,
"_appTitle": "KimerA"
},
"content": [
{
"files": [
"api/**.yml",
"api/index.md"
]
},
{
"files": [
"articles/**.md",
"articles/**/toc.yml",
"toc.yml",
"*.md"
]
}
],
"resource": [
{
"files": [
"images/**"
]
}
],
"overwrite": [
{
"files": [
"apidoc/**.md"
],
"exclude": [
"obj/**",
"_site/**"
]
}
],
"dest": "_site",
"globalMetadataFiles": [],
"fileMetadataFiles": [],
"template": [
"default",
"modern"
],
"postProcessors": [],
"markdownEngineName": "markdig",
"noLangKeyword": true,
"keepFileLink": true,
"cleanupCacheHistory": false
}
}

toc.yml

生成的 yml 文件名是根据命名空间来的,我希望一打开就是 KimerA.Core 这个命名空间内的东西,那么 homepage 就这么写(

1
2
3
- name: KimerA API Documentation
href: api/
homepage: api/KimerA.Core.yml

然后 index.md 里面随便写点东西,就可以直接 docfx .\docfx.json --serve

点上方按钮进去就是大概这样

一些可能的问题

  • 使用了 unsafe 代码,无法直接编译

    可以在 docfx.json 中的 metadata 中添加 "properties": { "AllowUnsafeBlocks": "true" }

    但是要注意, properties 中的属性的值都必须是 String 类型,这里填 true 会无法解析(x

  • 最近使用的时候遇到了 UnityEngine.dll 中缺少符号的问题,大概是 UnityEngine.dll 还会依赖其他的 dll,所以我直接把 editor 里面的 Data/Managed/UnityEngine/ 这个目录一起复制过去了,然后把配置文件里面的 references 改成 "UnityEngine/*.dll" 就可以了。

Welcome to my other publishing channels