# DocFX 文档生成指南

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

## 环境准备

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

   ```bash
   dotnet tool install -g docfx
   ```

## 文档结构

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

## 生成文档步骤

1. 清理旧的生成文件

   ```bash
   rm -rf docs/_site/
   rm -rf docs/api/
   ```

2. 生成 API 文档元数据

   ```bash
   cd docs
   docfx metadata
   ```

3. 构建网站

   ```bash
   docfx build
   ```

4. （可选）本地预览

   ```bash
   docfx serve _site
   ```

   然后访问 <http://localhost:8080>

## docfx.json 配置说明

```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>` 等标签

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

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

3. 图片和资源
   - 图片放在 `images` 目录
   - 使用相对路径引用
   - 控制图片大小适中

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

## 自动化脚本

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

```bash
#!/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 官方文档](https://dotnet.github.io/docfx/)
- [XML 文档注释指南](https://learn.microsoft.com/zh-cn/dotnet/csharp/language-reference/xmldoc/)