Docusaurus 配合 DocFX

目标 & 背景

最近公司刚刚搭好 Docusaurus 文档环境，刚好在即刻看到 叫我三叔就行 用户提到的 DocFX 自动生成 C# API 的工具，此工具最终会生成一组 yaml 文件，然后进行 web 的绘制，这个和 Docusaurus 刚好冲突

现有的文档不兼容，着实有些遗憾，本篇文章会介绍如何兼容这两个工具

DocFxMarkdownGen 工具

这个也是一个开源工具，其整体思路是将生成的 yaml 文件二次解析成 md 文件，但是该作者当前仓库版本的 Docusaurus 应该是跟我们的版本不一致，所以需要做一些小的修改

这里特指 Docusaurus 2.3.1 版本

具体改动可以参考 fix: fit Decusaurus 2.3.1 提交的 diff 内容

目录规划

在我们的文档中，包含了 N 个框架，因此在 website/Framework 下，就对应着 N 个文件夹

此处根据自己项目实际需要做调整，后续框架的名称都称为 XXFramework

.
├── APIGen
│   └── XXFramework # 存放 docfx 生成的文件和配置
├── README.md
├── Tools
│   └── DocFxMarkdownGen # 存放转换工具
└── website
    ├── Framework
    ├──── XXFramework # 当前框架
    ├──────API # 要自动生成的文档路径

docfx 使用

最终使用时你只需要关心如下内容，接下来挨个介绍如何使用

.
├── api         # docfx 生成的 yaml 文件夹
├── config.yaml # DocFxMarkdownGen 的配置文件
├── docfx.json # docfx 的配置文件
├── gen.sh  # 自动化脚本
└── namespace_ignore.yml # 忽略那些 namespace

1. 初始化 docfx

# 升级 docfx 版本
dotnet tool update -g docfx
# 到指定目录
cd APIGen/
# 初始化 docfx
docfx init --quit
# 修改工程文件夹为当前框架名
mv docfx_project XXFramework

2. 配置 docfx.json 文件

src: 如果你的项目是 Unity 项目，可以在 Library/ScriptAssemblies 找到对应域的 dll

{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "XXFramework.dll"
          ],
          "src": "XXFramework.dll的相对文件夹路径"
        }
      ],
      "dest": "api",
      "includePrivateMembers": false,
      "disableGitFeatures": false,
      "disableDefaultFilter": false,
      "namespaceLayout": "flattened",
      "filter": "namespace_ignore.yml"
    }
  ],
// 其余略
}

3. namespace_ignore.yml 配置

忽略下方两个命名空间的所有 API

apiRules:
- exclude:
    uidRegex: XXXFramework.XXX1
    type: Namespace
- exclude:
    uidRegex: XXXFramework.XXX2
    type: Namespace

4. config.yaml

如果你的目录层级跟我这里一样，这个文件就不需要修改

outputPath: ../../website/Framework/XXXFramework/API
yamlPath: ./api

5. 编译并拷贝 DocFxMarkdownGen 项目

编译过程我就不写了，自己 clone 一下 fork 的仓库，然后将 build 内容拷贝到 Tools/DocFxMarkdownGen 文件夹即可

6. gen.sh

#!/bin/bash

docfx docfx.json

dotnet ../../Tools/DocFxMarkdownGen/DocFxMarkdownGen.dll

当你需要生成 API 文档时，直接运行 gen.sh 就好了

参考

1. Docusaurus: https://docusaurus.io/zh-CN/docs/installation
2. DocFxMarkdownGen-Fork: https://github.com/LiuOcean/DocFxMarkdownGen
3. docfx: https://dotnet.github.io/docfx/