引子
同于生成API文档记录
参考
安装DocFx
使用 Chocolatey 安装
1 | choco install docfx -y. |
使用 Homebrew 安装
1 | brew install docfx. |
去 GitHub 下载文件安装
- 从 GitHub DocFx 下载 文件 docfx.zip
- 解压文件 docfx.zip
- 添加到环境变量 Path 中
验证安装是否成功
使用命令行
1 | $ docfx.exe --version |
使用 DocFx
使用 Visual Studio 集成 DocFx
- 使用 Visual Studio 创建 Class Library (.NET Framework) 项目
- 右键项目,选择 Manage NuGet Package
- 搜索并安装 docfx.console
- Build the project, and a _site folder will be generated with the documentation.
单独创建 DocFx 项目
- 创建 docfx init -q 项目
1 | $ docfx init -q |
1 | $ cd docfx_project |
- 修改 docfx.json 添加代码文档
原始 docfx.json1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17{
"metadata": [
{
"src": [
{
"files": [
"src/**.csproj"
]
}
],
"dest": "api",
"disableGitFeatures": false,
"disableDefaultFilter": false
}
],
...
}
修改为1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23{
"metadata": [
{
"src": [
{
"files": [
"FmoLib/**.csproj"
],
"exclude": [
"**/obj/**",
"**/bin/**",
"_site/**"
],
"cwd": ".."
}
],
"dest": "api",
"disableGitFeatures": false,
"disableDefaultFilter": false
}
],
...
}
生成 doc 文件
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35$ docfx.exe docfx.json --serve
$ treee -L 2
E:\projects\csharp\FmoLib\docfx_project
├── api
| ├── FmoLib.API.App.yml
| ├── ...
| ├── index.md
| └── toc.yml
├── apidoc
├── articles
| ├── intro.md
| └── toc.yml
├── docfx.json
├── images
├── index.md
├── obj
├── src
├── toc.yml
└── _site
├── api
├── articles
├── favicon.ico
├── fonts
├── index.html
├── logo.svg
├── manifest.json
├── search-stopwords.json
├── styles
├── toc.html
└── xrefmap.yml
directory: 11 file: 233
ignored
filterConfig.yml 配置
这个文件可以包含包括的文件和不包括的,包括的权限比不包括大,默认是包括所有文件
docfx.json 关联 filterConfig.yml
1 | { |
包括的文件使用include 不包括使用 exclude
文件示例1
2
3
4
5apiRules:
- include:
uidRegex: ^Microsoft\.DevDiv\.SpecialCase
- exclude:
uidRegex: ^Microsoft\.DevDiv
因为 uidRegex 是匹配,所以对于.需要加上\
强大的ms还可以匹配是什么类型,提供的:
1 | Namespace |
如果要忽略命名空间是 lindexi.laji 的代码,请看下面代码1
2
3
4apiRules:
- exclude:
uidRegex: ^lindexi\.laji*
type: Namespace
DocFx生成PDF文件
安装必要的插件 wkhtmltopdf
使用 Chocolatey 安装
1 | choco install wkhtmltopdf -y. |
手动安装
- 下载 wkhtmltopdf
- 安装 wkhtmltopdf
- 添加到环境变量 Path 中
修改 docfx.json
添加 pdf 信息1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78{
"metadata": [
...
],
"build": {
...
},
"pdf": {
"content": [
{
"files": [
"api/**.yml",
"api-vb/**.yml"
],
"exclude": [
"**/toc.yml",
"**/toc.md",
"README.md",
"source_codes/**"
]
},
{
"files": [
"articles/**.md",
"articles/**/toc.yml",
"toc.yml",
"*.md",
"pdf/*"
],
"exclude": [
"**/bin/**",
"**/obj/**",
"_site_pdf/**",
"**/toc.yml",
"**/toc.md",
"README.md",
"source_codes/**"
]
},
{
"files": "pdf/toc.yml"
}
],
"resource": [
{
"files": [
"images/**"
],
"exclude": [
"**/bin/**",
"**/obj/**",
"_site_pdf/**",
"README.md",
"source_codes/**"
]
}
],
"overwrite": [
{
"files": [
"apidoc/**.md"
],
"exclude": [
"**/bin/**",
"**/obj/**",
"_site_pdf/**",
"README.md",
"source_codes/**"
]
}
],
"dest": "_site_pdf",
"template": ["pdf.default"],
"wkhtmltopdf": {
"additionalArguments": "--enable-local-file-access"
}
}
}
添加 “pdf/toc.yml” 文件
1 | - name: Documentation |
1 | $ treee -l 2 |