使用 DocFX 生成 Unity 文档 - 配置详解

使用 DocFX 生成 Unity 文档 - 配置详解

DocFX 是一款强大的工具，可以帮助你轻松生成高质量的文档。本文将详细介绍如何使用 DocFX 生成 Unity 文档，包括 docfx.json 配置文件解析和生成文档命令。

docfx.json 配置文件解析

下面是一个示例的 docfx.json 配置文件，用于生成 Unity 文档：

{
  'metadata': [
    {
      'src': [
        {
          'files': [
            '**/*.cs'
          ],
          'exclude': [
            '**/obj/**',
            '**/bin/**'
          ]
        }
      ],
      'dest': 'api'
    }
  ],
  'build': {
    'content': [
      {
        'files': [
          'Assets/**/*.md'
        ],
        'exclude': [
          'Assets/**/Editor/**',
          'Assets/**/Gizmos/**',
          'Assets/**/Plugins/**'
        ]
      }
    ],
    'globalMetadata': {
      '_appTitle': 'Unity Documentation',
      '_appFooter': 'Generated by DocFX',
      '_enableSearch': true,
      '_enableSidebar': true,
      '_enableNavbar': true
    },
    'template': [
      'default'
    ],
    'overwrite': [
      'api'
    ],
    'dest': 'docs'
  }
}

配置项解释

• metadata：指定需要分析的源代码文件和生成的 API 文档目录。
  • src.files: 指定要分析的源代码文件，例如 **/*.cs 表示所有 *.cs 文件。
  • src.exclude: 指定要排除的文件或目录，例如 **/obj/** 和 **/bin/** 分别表示排除 obj 和 bin 目录下的所有文件。
  • dest: 指定生成的 API 文档的目录。
• build.content：指定需要包含在文档中的额外内容，例如 Markdown 文件。
  • files: 指定要包含的 Markdown 文件，例如 Assets/**/*.md 表示所有 Assets 目录下的 Markdown 文件。
  • exclude: 指定要排除的 Markdown 文件或目录。
• build.globalMetadata：全局元数据，可以用于定义文档的标题、页脚等。
  • _appTitle: 文档标题。
  • _appFooter: 文档页脚。
  • _enableSearch: 是否启用文档搜索功能。
  • _enableSidebar: 是否启用侧边栏。
  • _enableNavbar: 是否启用导航栏。
• build.template: 指定使用的文档模板，这里使用了默认模板。
• build.overwrite: 指定需要覆盖的目录，例如 api 表示覆盖 api 目录下的所有文件。
• build.dest: 生成的文档的输出目录。

生成 Unity 文档

配置好 docfx.json 后，可以使用以下命令生成 Unity 文档：

docfx docfx.json

请确保在运行上述命令之前已经安装了 DocFX 并正确配置了环境变量。

总结

本文详细介绍了使用 DocFX 生成 Unity 文档的方法，包括 docfx.json 配置文件解析和生成文档命令。希望本文可以帮助你快速创建清晰、易读的 Unity 文档。