使用DocFx生成文档网站并将其发布到GitHub Pages
目录
在本文中，我们将使用DocFx为Windows计算机中的Visual Studio C＃解决方案生成文档。
介绍
DocFx是生成文档的命令行工具。
DocFx建立了一个结合两个来源的文档网站：
- 它从源代码文件中的注释中收集参考文档
- 由用户以Markdown文件形式提供给DocFx的概念性文档
根据DocFx网站：
“DocFX可以从源代码（包括.NET，REST，JavaScript，Java，Python和TypeScript）以及原始Markdown文件中生成文档。”
并且：
“DocFX可以在Linux，macOS和Windows上运行。生成的静态网站可以部署到任何主机，例如GitHub Pages或Azure网站，而无需进行其他配置。”
DocFx是由Microsoft开发的一种开源工具，正如该公司所说，它是用于构建Microsoft文档网站的工具。
在本文中，我们将使用DocFx为Windows计算机中的Visual Studio C＃解决方案生成文档。
DocFx安装
下载和安装DocFx的最简单方法是使用Windows版Chocolatey软件包管理器。以管理员身份打开终端并执行以下操作：
choco install docfx -y上面也将DocFx添加到PATH环境变量中。
Visual Studio中的测试解决方案
打开Visual Studio并使用两个项目创建一个解决方案：一个Library项目和一个Windows Forms项目。
这是文件夹结构：
Solution
+ App
+ Lib
Solution.sln对于每个项目，请转到属性|生成并选中XML文档文件复选框。
向项目中添加一些类并记录这些类。这是通过在类、方法和属性上添加三斜杠注释来完成的。
构建解决方案。
使用docfx init设置DocFx
DocFx文档提供了两个演练。
这些演练说明，我们通过打开终端cd到solutionF文件夹init DocFx ，然后键入docfx init -q以初始化项目。
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部分对DocFx来说：
- 在哪里找到源代码文件，从中收集注释
- 将收集的材料放在哪里
- 以及如何过滤源文件中发现的类型的固有成员
我们的metadata部分对DocFx来说：
- 从rool解决方案文件夹（"src": ".."）开始在所有csproj文件（"files": [ "**/**.csproj" ]）中查找源代码文件
- 将收集的资料放置到名为reference（"dest": "reference",）的文件夹中
- 并根据提供的yml文件（"filter": "filterConfig.yml"）过滤继承的成员
该引用文件夹将由DocFx创建，如果不存在。
构建部分
Build部分对DocFx来说：
- 对于两种类型，从哪里找到要构建的内容，从源文件收集的DocFx内容（引用上）和用户作为Markdown文件提供的内容（概念上）
- 在哪里可以找到Markdown文件中使用的图像
- “已编译”输出的位置，即它生成的网站
- 以及使用什么模板
我们的build部分对DocFx来说：
- 参考内容位于参考文件夹中，而概念内容位于概念文件夹中
- 图像在图像文件夹中
- 将生成的网站放置到../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文件
“过滤器配置文件为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格式的结构化数据模型或Metadata文件。除此之外，DocFX引入了一种使用目录文件或TOC文件来组织这些文件的方法，以便用户可以浏览元数据文件和概念文件。”
下面列出了使用的三个toc.yml文件：
1、Concepts/toc.yml：
- name: Easy
href: Easy/toc.yml
topicHref: Easy/Abstract.md
- name: Advanced
href: Advanced/toc.yml
topicHref: Advanced/Abstract.md2、Concepts/Advanced/toc.yml：
- name: Advanced Overview Title
href: Advanced.md3、Concepts/Easy/toc.yml：
- name: Easy Overview Title
href: Easy.md- name条目是要单击的标题，即链接，将由生成的站点的目录显示。
- href条目说明单击该标题时的导航位置。
- 可选的topicHref说明要显示的内容文件。当href链接到另一个toc.yml（即另一个目录）时使用，但用户希望向访问者提供某种关于它将在该链接中找到的内容的抽象。
.gitignore文件
docfx init -q命令在DocFx文件夹中添加一个.gitignore文件。创建具有以下内容的.gitignore文件，并将其放入DocFx文件夹中。
/**/DROP/
/**/TEMP/
/**/packages/
/**/bin/
/**/obj/
reference生成文档站点
为了生成网站，请打开终端，cd进入DocFx文件夹，然后键入：
docfx网站已生成。
现在该预览该网站了。根据文档：
“如果未使用端口8080，则docfx将在http://localhost:8080下托管_site。如果正在使用8080，则可以使用docfx serve _site -p <port>更改由docfx使用的端口。”
要预览网站，请cd到docs：
cd ../docs然后输入：
docfx serve或者如果该端口8080是由另一个应用程序占用的，则只需使用另一个端口：
docfx serve -p 8081现在，文档站点正在运行。
打开浏览器并导航到http://localhost:8080。
或者，如果将生成的站点的文件夹放在DocFx文件夹下，则可以只用一行就可以构建和运行该站点。
docfx --serve您可以删除生成的文件夹，reference和docs。它们会在每个版本中重新创建。
将生成的文档站点发布到GitHub Pages
- Push 您的本地git存储库到github远程存储库。
- 在github存储库中，转到“设置”（最右边带有齿轮图标）。
- 向下滚动到GitHub Pages部分。
- 选择master分支/ docs文件夹作为Source。
- 千万不要选择主题。
就这样。您的文档站点将很快通过以下网址提供：
`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）