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

青岛网站策划中国最大的销售网站

wzjs 2025/9/4 13:01:33

青岛网站策划,中国最大的销售网站,江苏苏州有什么好玩的,沈阳网站seo优化哪家好DocFX 是一个强大的文档生成工具，特别适合为 .NET 项目生成 API 文档和开发文档。以下是使用 DocFX 的详细步骤，从安装到生成文档的全过程： 1. 安装 DocFX 1.1 安装 .NET SDK DocFX 是基于 .NET 的工具，因此需要先安装 .NET SDK…

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 Documentationon:push:branches:- mainjobs:build:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v2- name: Setup .NETuses: actions/setup-dotnet@v1with:dotnet-version: 6.x- name: Install DocFXrun: dotnet tool install -g docfx- name: Generate Documentationrun: docfx build- name: Upload Documentationuses: actions/upload-artifact@v2with:name: documentationpath: _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 输出目录}
}