当前位置：首页 > news >正文

笔记：介绍如何使用Docfx生成开发文档

news 来源：原创 2025/5/9 10:33:01

DocFX 是一个强大的文档生成工具，特别适合为 .NET 项目生成 API 文档和开发文档。以下是使用 DocFX 的详细步骤，从安装到生成文档的全过程：

1. 安装 DocFX

1.1 安装 .NET SDK

DocFX 是基于 .NET 的工具，因此需要先安装 .NET SDK。

下载并安装 .NET SDK（推荐使用 .NET 6 或更高版本）：
- 官方下载地址：https://dotnet.microsoft.com/download
验证安装是否成功：
```
dotnet --version
```

1.2 安装 DocFX

通过 .NET 全局工具安装 DocFX：

dotnet tool install -g docfx

验证安装：
```
docfx --version
```

在这里插入图片描述

2. 初始化 DocFX 项目

2.1 打开当前项目文件夹并初始化项目

:: 初始化数据
@echo off
cd /d "%~dp0"
docfx init
pause

其中docfx init命令用来初始化项目数据

这会生成以下文件和文件夹：
- docfx.json：配置文件。
- api/：存放 API 文档的文件夹。
- articles/：存放 Markdown 文件的文件夹。
- toc.yml：目录文件。

3. 配置 `docfx.json`

docfx.json 是 DocFX 的配置文件，用于指定文档生成的行为。

示例配置：

{
  "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json",
  "metadata": [
    {
      "src": [
        {
          "src": "../Source/WPF-Control/Source/Providers", // 相对路径移到 src 字段
          "files": [ "**/*.csproj" ], // 使用通配符匹配 .csproj 文件
          "exclude": [ "**/bin/**", "**/obj/**" ]
        }
      ],
      "dest": "api"
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "**/*.{md,yml}"
        ],
        "exclude": [
          "_site/**"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ]
      }
    ],
    "output": "_site",
    "template": [
      "default",
      "modern"
    ],
    "globalMetadata": {
      "_appName": "WPF-Control",
      "_appTitle": "WPF-Control",
      "_enableSearch": true,
      "pdf": true
    }
  }
}

配置说明：

metadata：指定要生成 API 文档的项目文件（如 .csproj）。
build：指定文档生成的内容和输出目录。

检查配置是否有效

:: 检查配置是否正确
docfx metadata
pause

4. 生成文档

4.1 生成文档

在项目根目录运行以下命令生成文档：

docfx build

生成的文档会保存在 _site 文件夹中。

4.2 预览文档

启动本地服务器预览文档：

docfx serve _site

访问 http://localhost:8080 查看生成的 HTML 文档。

或者直接使用命令生成并预览当当

:: 生成数据并运行服务
docfx docfx.json --serve
pause

5. 编写文档内容

5.1 编写 API 文档

确保项目启用了 XML 文档注释（在 .csproj 中添加 <GenerateDocumentationFile>true</GenerateDocumentationFile>）。
DocFX 会自动从 XML 文档注释生成 API 文档。

5.2 编写 Markdown 文档

在 articles/ 文件夹中添加 Markdown 文件，编写额外的文档内容。

示例 Markdown 文件：

# 欢迎使用 DocFX

这是一个示例文档。

## 功能
- 生成 API 文档。
- 支持 Markdown 文件。

5.3 配置目录

编辑 toc.yml 文件，配置文档的目录结构。

示例 toc.yml：

- name: 首页
  href: index.md
- name: API 文档
  href: api/
- name: 示例文章
  href: articles/sample.md

6. 高级功能

6.1 多语言支持

DocFX 支持生成多语言版本的文档。

示例配置：

{
  "build": {
    "content": [
      {
        "files": ["api/**.yml"],
        "src": "en",
        "dest": "en"
      },
      {
        "files": ["api/**.yml"],
        "src": "zh-cn",
        "dest": "zh-cn"
      },
      {
        "files": ["articles/en/**/*.md"],
        "src": "en",
        "dest": "en"
      },
      {
        "files": ["articles/zh-cn/**/*.md"],
        "src": "zh-cn",
        "dest": "zh-cn"
      }
    ],
    "dest": "_site",
    "globalMetadata": {
      "_appTitle": "我的文档",
      "_appFooter": "版权所有 © 2023",
      "_enableSearch": true
    },
    "locales": {
      "en": "English",
      "zh-cn": "简体中文"
    }
  }
}

6.2 自定义主题

DocFX 支持自定义主题，允许你修改文档的外观和布局。

示例：

创建自定义主题文件夹（如 custom_template）。
复制默认主题文件到 custom_template 文件夹中。
修改模板文件（如 styles/docfx.css 或 partials/head.tmpl.partial）。

在 docfx.json 中指定自定义主题：

{
  "build": {
    "template": ["./custom_template"]  // 指定自定义主题路径
  }
}

6.3 集成 CI/CD

可以将 DocFX 集成到 CI/CD 流程中，自动化生成和部署文档。

示例 GitHub Actions 配置：

name: Generate Documentation

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup .NET
        uses: actions/setup-dotnet@v1
        with:
          dotnet-version: 6.x
      - name: Install DocFX
        run: dotnet tool install -g docfx
      - name: Generate Documentation
        run: docfx build
      - name: Upload Documentation
        uses: actions/upload-artifact@v2
        with:
          name: documentation
          path: _site

7. **示例项目结构

假设项目结构如下：

D:\GitHub\WPF-VisionMaster\
├── Document\
│   ├── Doc\
│   │   ├── docfx.json
│   │   ├── articles\
│   │   │   ├── index.md
├── Source\
│   ├── Apps\
│   │   ├── H.App.VisionMaster\
│   │   │   ├── H.App.VisionMaster.csproj
│   │   │   ├── ExampleClass.cs

对应的 `docfx.json` 配置：

{
  "metadata": [
    {
      "src": [
        {
          "src": "../../Source/Apps/H.App.VisionMaster",  // 相对路径
          "files": ["*.csproj"],  // 匹配 .csproj 文件
          "exclude": ["**/bin/**", "**/obj/**"]
        }
      ],
      "dest": "api"  // 生成的 API 文档输出目录
    }
  ],
  "build": {
    "content": [
      {
        "files": ["api/**.yml", "articles/**/*.md"]  // 包含 API 文档和 Markdown 文件
      }
    ],
    "dest": "_site"  // 生成的 HTML 输出目录
  }
}