ThreatSourceLibaray/docfx-guide.md

DocFX 文档生成指南

本指南说明如何使用 DocFX 为 ThreatSource 库生成 API 文档。

环境准备

1. 安装 .NET SDK（需要 .NET 8.0 或更高版本）

2. 安装 DocFX

   dotnet tool install -g docfx
   

文档结构

docs/
├── api/            # API 文档（自动生成）
├── articles/       # 手写文档
├── examples/       # 示例代码
├── images/         # 图片资源
├── _site/         # 生成的静态网站
├── docfx.json      # DocFX 配置文件
└── toc.yml         # 文档目录结构

生成文档步骤

1. 清理旧的生成文件

   rm -rf docs/_site/
   rm -rf docs/api/
   

2. 生成 API 文档元数据

   cd docs
   docfx metadata
   

3. 构建网站

   docfx build
   

4. （可选）本地预览

   docfx serve _site
   

   然后访问 http://localhost:8080

docfx.json 配置说明

{
  "metadata": [
    {
      "src": [
        {
          "src": "../",                    // 源代码根目录
          "files": [
            "ThreatSource/**.csproj"       // 项目文件
          ]
        }
      ],
      "dest": "api",                       // API文档输出目录
      "disableGitFeatures": false,
      "disableDefaultFilter": false
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "api/**.yml",                    // API文档
          "api/index.md"
        ]
      },
      {
        "files": [
          "articles/**.md",                // 文章
          "articles/**/toc.yml",
          "examples/**.md",                // 示例
          "examples/**/toc.yml",
          "toc.yml",
          "*.md"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"                      // 资源文件
        ]
      }
    ],
    "dest": "_site",                       // 网站输出目录
    "globalMetadataFiles": [],
    "fileMetadataFiles": [],
    "template": [
      "default"                            // 使用默认模板
    ],
    "postProcessors": [],
    "markdownEngineName": "markdig",
    "noLangKeyword": false,
    "keepFileLink": false,
    "cleanupCacheHistory": false,
    "disableGitFeatures": false
  }
}

注意事项

1. 代码注释规范

   • 使用 XML 文档注释
   • 为公开的类、方法、属性添加注释
   • 使用 <summary>、<param>、<returns> 等标签

   /// <summary>
   /// 类的功能描述
   /// </summary>
   public class MyClass
   {
       /// <summary>
       /// 方法的功能描述
       /// </summary>
       /// <param name="input">参数说明</param>
       /// <returns>返回值说明</returns>
       public string MyMethod(string input)
       {
           // ...
       }
   }
   

2. 文档组织

   • 使用 toc.yml 组织文档结构
   • 保持文档层次清晰
   • 适当使用交叉引用

3. 图片和资源

   • 图片放在 images 目录
   • 使用相对路径引用
   • 控制图片大小适中

4. 常见问题

   • 如果生成失败，检查项目引用是否正确
   • 确保所有必要的源代码文件都被包含
   • 检查文档注释的格式是否正确

自动化脚本

可以创建以下脚本来简化文档生成过程：

#!/bin/bash
# generate-docs.sh

# 清理旧文件
rm -rf docs/_site/
rm -rf docs/api/

# 生成文档
cd docs
docfx metadata
docfx build

# 启动预览（可选）
# docfx serve _site

更新文档

1. 修改源代码注释后：

   • 重新生成 API 文档
   • 检查生成的文档是否正确

2. 修改手写文档后：

   • 直接重新构建网站
   • 不需要重新生成 API 元数据

相关资源

• DocFX 官方文档
• XML 文档注释指南