Unity 项目文档生成

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

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

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”

{
  "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" 就可以了。