193 lines
3.9 KiB
Markdown
193 lines
3.9 KiB
Markdown
# 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/)
|