使用 DocFx 生成文档网站并将其发布到 GitHub Pages
4.00/5 (1投票)
如何使用开源 DocFx 生成文档网站（以及 PDF 文件），并将该网站发布到 GitHub Pages
目录
- 引言
- DocFx 安装
- Visual Studio 中的一个测试解决方案
- 使用 docfx init 设置 DocFx
- 手动设置 DocFx
- docfx.json 配置文件详解
- filterConfig.yml 文件
- 概念性文档和 TOC（目录）文件
- .gitignore 文件
- 生成文档网站
- 将生成的文档网站发布到 GitHub Pages
- PDF 冒险
- 历史
引言
DocFx 是一个命令行工具，用于生成文档。
DocFx 构建了一个结合了两种来源的文档网站：
- 引用（reference）文档，它从源代码文件中的注释中收集。
- 概念性（conceptual）文档，由用户以 Markdown 文件的形式提供给 DocFx。
根据 DocFx 网站的说法：
"DocFX 可以从源代码（包括 .NET、REST、JavaScript、Java、Python 和 TypeScript）以及原始 Markdown 文件生成文档。"
还有
"DocFX 可以在 Linux、macOS 和 Windows 上运行。生成的静态网站可以部署到任何主机，如 GitHub Pages 或 Azure Websites，无需额外配置。"
DocFx 是由 Microsoft 开发的 开源工具，并且 正如该公司所说，它是用于构建 Microsoft 文档 网站的工具。
在这篇文章中，我们将使用 DocFx 为 Windows 机器上的 Visual Studio C# 解决方案生成文档。
DocFx 安装
下载和安装 DocFx 最简单的方法是使用 Windows 的 Chocolatey 包管理器。以管理员身份打开终端并执行以下命令：
choco install docfx -y
上面的命令还会将 DocFx 添加到 PATH 环境变量中。
Visual Studio 中的一个测试解决方案
打开 Visual Studio 并创建一个包含两个项目的解决方案：一个类库项目和一个 Windows Forms 项目。
文件夹结构如下：
Solution
+ App
+ Lib
Solution.sln
对于每个项目，转到 **属性 | 生成**，然后勾选 **XML 文档文件** 复选框。
为两个项目添加一些类并记录这些类。这是通过在类、方法和属性前添加三斜杠注释来完成的。
构建解决方案。
使用 docfx init 设置 DocFx
DocFx 文档提供了 两个演练教程。
这些演练教程指出，我们通过打开终端、cd 到解决方案文件夹，然后键入 docfx init -q 来初始化 DocFx 项目。
cd C:\Solution
docfx init -q
-q 参数表示 quiet（安静模式）。否则，它会经过一系列用户需要回答的问题。
上面的命令会在根解决方案文件夹中创建一个 docfx_project 文件夹，并向其中添加一些子文件夹和文件。docfx_project 中最重要的文件是 docfx.json，它是 DocFx 的配置文件。
"docfx.json 是 docfx 用于生成文档的配置文件"
在生成的 docfx.json 中，所有文件夹引用都是错误的。并且创建的一些文件夹根本不需要。
因此，删除 docfx_project 文件夹。我们将采用自己的方式。
手动设置 DocFx
我们需要在根解决方案文件夹中创建一个子文件夹来存放 DocFx 文件和生成的文档。创建新文件夹并命名为 DocFx。
Solution
+ App
+ DocFx
+ Lib
Solution.sln
在 DocFx 文件夹中，创建一个空的 docfx.json 文件，用 Visual Studio 打开它，然后添加以下内容：
{
"metadata": [
{
"src": [
{
"files": [ "**/**.csproj" ],
"src": ".."
}
],
"dest": "reference",
"disableGitFeatures": false,
"disableDefaultFilter": false,
"filter": "filterConfig.yml"
}
],
"build": {
"content": [
{
"files": [
"reference/**.yml",
"reference/index.md"
]
},
{
"files": [
"Concepts/toc.yml",
"Concepts/**.md",
"Concepts/**/toc.yml",
"toc.yml",
"*.md"
]
}
],
"resource": [
{
"files": [ "images/**" ]
}
],
"dest": "../docs",
"globalMetadataFiles": [],
"fileMetadataFiles": [],
"template": [ "default" ],
"postProcessors": [],
"markdownEngineName": "markdig",
"noLangKeyword": false,
"keepFileLink": false,
"cleanupCacheHistory": false,
"disableGitFeatures": false
}
}
docfx.json 配置文件详解
docfx.json 包含两个部分：metadata 和 build。可能还有一个第三部分 pdf，但我们将把这个……冒险留到以后。
元数据（metadata）部分
metadata 部分告诉 DocFx：
- 从哪里查找源代码文件以收集注释。
- 将收集到的资料放在哪里。
- 以及如何过滤源代码文件中找到的类型的继承成员。
我们的 metadata 部分告诉 DocFx：
- 从根解决方案文件夹（
"src": ".."）开始，查找所有csproj文件（"files": [ "**/**.csproj" ]）中的源代码文件。 - 将收集到的资料放在一个名为
reference的文件夹中（"dest": "reference",）。 - 并根据提供的
yml文件（"filter": "filterConfig.yml"）过滤继承的成员。
如果 reference 文件夹不存在，DocFx 会创建它。
构建（Build）部分
build 部分告诉 DocFx：
- 从哪里查找要构建的内容，包括两种类型的内容：DocFx 从源文件收集的内容（引用）和用户提供的 Markdown 文件内容（概念性）。
- 从哪里查找 Markdown 文件中使用的图像。
- 将“已编译”的输出（即它生成的网站）放在哪里。
- 以及使用哪个模板。
我们的 build 部分告诉 DocFx：
- 引用内容在 reference 文件夹中，而概念性内容在 Concepts 文件夹中。
- 图像在 images 文件夹中。
- 将生成的网站放置在 ../docs 文件夹中（
"dest": "../docs"）。 - 使用
default模板。
docs 文件夹
我们指示 DocFx 将生成的网站放置在根解决方案文件夹下的 docs 文件夹中。这将导致以下文件夹结构：
Solution
+ App
+ DocFx
+ docs
+ Lib
Solution.sln
您可以指示 DocFx 将生成的网站放置在任何您喜欢的文件夹中。
我们将其命名为 docs 文件夹并将其放置在根解决方案文件夹下，因为 GitHub Pages 需要这样。
如果您使用 GitHub 来托管您的开源项目，并且希望为您的项目提供一个漂亮的文档网站，您可以通过将文档网站放在根目录下的 docs 文件夹中，并将该 docs 文件夹设置为 GitHub Pages 站点的 发布源 来轻松实现。
filterConfig.yml 文件
正如 DocFx 文档所说：
"过滤器配置文件是 YAML 格式的。您可以通过提供过滤器配置文件并指定其路径来过滤掉不需要的 API 或属性。"
放置一个 filterConfig.yml 文件，内容如下：
apiRules:
- exclude:
# inherited members from Form
uidRegex: ^System\.Windows\.Forms\.Form\..*$
type: Member
- exclude:
# inherited members from Control
uidRegex: ^System\.Windows\.Forms\.Control\..*$
type: Member
- exclude:
# mentioning types from System.* namespace
uidRegex: ^System\..*$
type: Type
- exclude:
# mentioning types from Microsoft.* namespace
uidRegex: ^Microsoft\..*$
type: Type
注意：包含
uidRegex和type条目的行应以两个空格开头。YAML 语言使用空格缩进。
概念性文档和 TOC（目录）文件
DocFx 支持包含概念性文档的 Markdown 文件，这些文件由用户编写。它使用 TOC（目录）YAML 文件来组织这些 Markdown 文件。
在 DocFx 文件夹下，添加一个 index.md 文件，内容随意。
我的 DocFx 文件夹如下：
DocFx
docfx.json
index.md
.gitignore
filterConfig.yml
toc.yml
在 DocFx 文件夹中，创建一个 Concepts 子文件夹，并添加以下文件夹和文件：
Concepts
+ Advanced
Abstract.md
Advanced.md
toc.yml
+ Easy
Abstract.md
Easy.md
toc.yml
Abstract.md
toc.yml
您可以将任何您喜欢的内容放在这些 Markdown 文件中。通常，这些文件包含关于如何使用引用的 API 的概念性概述。
关于 TOC 文件，您可以参考相关的 DocFx 文档，其中提到：
"DocFX 支持处理 Markdown 文件或概念性文件，以及 YAML 或 JSON 格式的结构化数据模型或元数据文件。此外，DocFX 引入了一种使用目录文件或 TOC 文件来组织这些文件的方式，以便用户可以浏览元数据文件和概念性文件。"
下面是使用的三个 toc.yml 文件：
- Concepts/toc.yml:
- name: Easy href: Easy/toc.yml topicHref: Easy/Abstract.md - name: Advanced href: Advanced/toc.yml topicHref: Advanced/Abstract.md
- Concepts/Advanced/toc.yml:
- name: Advanced Overview Title href: Advanced.md
- Concepts/Easy/toc.yml:
- name: Easy Overview Title href: Easy.md
-
name条目是 TOC 在生成站点上显示的、可点击的标题，即链接。 -
href条目指定了点击该标题时导航到的位置。 -
可选的
topicHref指定要显示的内容文件。当href链接到另一个 toc.yml（即另一个目录）时使用，但用户希望为访问者提供某种抽象，让他们知道在这个链接中会找到什么。
-
.gitignore 文件
docfx init -q 命令会在 DocFx 文件夹中添加一个 .gitignore 文件。创建一个 .gitignore 文件，内容如下，并将其放置在 DocFx 文件夹中。
/**/DROP/
/**/TEMP/
/**/packages/
/**/bin/
/**/obj/
reference
生成文档网站
为了生成网站，打开一个终端，cd 到 DocFx 文件夹，然后键入：
docfx
网站已生成。
现在是预览网站的时候了。根据 文档：
"如果端口 8080 未被使用，docfx 将在 https://:8080 下托管 _site。如果 8080 已在使用中，您可以使用 docfx serve _site -p <port> 将 docfx 使用的端口更改为其他端口。"
要预览网站，cd 到 docs 文件夹：
cd ../docs
然后键入：
docfx serve
或者，如果端口 8080 被另一个应用程序占用，请使用其他端口：
docfx serve -p 8081
现在文档网站正在运行。
打开浏览器并导航到 https://:8080。
或者，如果您将生成的站点文件夹放在 DocFx 文件夹下，您可以用一行命令构建和运行站点。
docfx --serve
您可以删除生成的文件夹 reference 和 docs。它们将在每次构建时重新创建。
将生成的文档网站发布到 GitHub Pages
- 将您的本地 git 仓库
Push到您的 GitHub 远程仓库。 - 在 GitHub 仓库中，转到 **Settings**（设置）（位于最右边，带有一个齿轮图标）。
- 向下滚动到 **GitHub Pages** 部分。
- 选择 **master 分支 /docs 文件夹** 作为 Source（源）。
- 不要选择 theme（主题）。
就这样。您的文档网站很快就会可用，如果不是立即的话，将在：
`https://USER_NAME.github.io/PROJECT_NAME/`
PDF 冒险
DocFx 可以生成一个 PDF 文件，包含整个生成的文档。但并非没有 问题。
DocFx 使用 wkhtmltopdf 工具生成 PDF 输出。
要下载和安装 wkhtmltopdf，请以管理员身份打开终端并键入：
choco install wkhtmltopdf -y
为了生成那个令人垂涎的 PDF 文件，用户必须阅读并……理解 DocFx 提供的相关文档。
其中一部分信息可以在 用户手册中找到，另一部分可以在 第三个演练教程中找到。
经过大量的挖掘和实验，这是我的方法：
- 在 DocFx 文件夹中添加一个 PDF 文件夹。
- 在 PDF 文件夹中添加以下 toc.yml 文件：
- name: Concepts href: ../Concepts/toc.yml - name: Reference href: ../reference/toc.yml
- 在 docfx.json 中添加一个
pdf部分，内容如下："pdf": { "content": [ { "files": [ "PDF/toc.yml" ] }, { "files": [ "reference/**.yml", "reference/index.md" ], "exclude": [ "**/toc.yml", "**/toc.md" ] }, { "files": [ "Concepts/**.md", "Concepts/**/toc.yml", "toc.yml", "*.md" ], "exclude": [ "**/bin/**", "**/obj/**", "PDF/**", "**/toc.yml", "**/toc.md" ] } ], "resource": [ { "files": [ "images/**" ], "exclude": [ "**/bin/**", "**/obj/**", "PDF/**" ] } ], "dest": "_pdf", "outline": "NoOutline" } - 打开一个终端，
cd到 DocFx 文件夹，然后键入：docfx pdf
这将生成一个 PDF 文件，但没有大纲，即 PDF TOC。显然，存在一个问题，大纲没有正确生成。所以我通过设置
"outline": "NoOutline"来停用了它。
测试于
- Windows 10
- docfx 2.48.1.0
- wkhtmltopdf 0.12.5 (已打补丁的 qt)
历史
- 2020年2月17日：初始版本