0%

CSharp ApiDoc 自动生成API文档

引子

同于生成API文档记录

参考

安装DocFx

使用 Chocolatey 安装

1
choco install docfx -y.

使用 Homebrew 安装

1
brew install docfx.

GitHub 下载文件安装

  • GitHub DocFx 下载 文件 docfx.zip
  • 解压文件 docfx.zip
  • 添加到环境变量 Path

验证安装是否成功

使用命令行

1
2
3
4
$ docfx.exe --version
docfx 2.56.2.0
Copyright (C) 2020 ? Microsoft Corporation. All rights reserved.
This is open-source software under MIT License.

使用 DocFx

使用 Visual Studio 集成 DocFx

  1. 使用 Visual Studio 创建 Class Library (.NET Framework) 项目
  2. 右键项目,选择 Manage NuGet Package
  3. 搜索并安装 docfx.console
  4. Build the project, and a _site folder will be generated with the documentation.

单独创建 DocFx 项目

  1. 创建 docfx init -q 项目
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$ docfx init -q
$ treee -L 2

E:\projects\csharp\FmoLib
├── Debugger
├── docfx_project
├── FmoLib
├── FmoLib.sln
├── FmoLibDemo
├── link.cmd
├── README.md
└── ShareLibrary

directory: 5 file: 3

ignored
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$ cd docfx_project
$ treee -L 2

E:\projects\csharp\FmoLib\docfx_project
├── api
├── apidoc
├── articles
├── docfx.json
├── images
├── index.md
├── src
└── toc.yml

directory: 5 file: 3

ignored
  1. 修改 docfx.json 添加代码文档

原始 docfx.json

1
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
}
],
...
}

  1. 生成 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

  2. 访问 http://localhost:8080

filterConfig.yml 配置

这个文件可以包含包括的文件和不包括的,包括的权限比不包括大,默认是包括所有文件

docfx.json 关联 filterConfig.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
{
"metadata": [
{
"src": [
...
],
"dest": "api",
"disableGitFeatures": false,
"disableDefaultFilter": false,
"filter": "filterConfig.yml"
}
]
}

包括的文件使用include 不包括使用 exclude
文件示例

1
2
3
4
5
apiRules:
- include:
uidRegex: ^Microsoft\.DevDiv\.SpecialCase
- exclude:
uidRegex: ^Microsoft\.DevDiv

因为 uidRegex 是匹配,所以对于.需要加上\

强大的ms还可以匹配是什么类型,提供的:

1
2
3
4
5
6
7
8
9
10
11
12
Namespace  
Type
Class
Struct
Enum
Interface
Delegate
Member
Event
Field
Method
Property

如果要忽略命名空间是 lindexi.laji 的代码,请看下面代码

1
2
3
4
apiRules:
- exclude:
uidRegex: ^lindexi\.laji*
type: Namespace

DocFx生成PDF文件

安装必要的插件 wkhtmltopdf

使用 Chocolatey 安装

1
choco install wkhtmltopdf -y.

手动安装

  1. 下载 wkhtmltopdf
  2. 安装 wkhtmltopdf
  3. 添加到环境变量 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
2
- name: Documentation
href: ../api/toc.yml
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
$ treee -l 2

E:\projects\csharp\FmoLib\docfx_project
├── api
| ├── FmoLib.API.App.yml
| ├── ...
| ├── FmoLib.yml
| ├── index.md
| └── toc.yml
├── apidoc
├── articles
| ├── intro.md
| └── toc.yml
├── docfx.json
├── docfx_pdf.json
├── filterConfig.yml
├── images
├── index.md
├── obj
├── pdf
| └── toc.yml
├── src
├── toc.yml
├── _site
| ├── api
| ├── articles
| ├── favicon.ico
| ├── fonts
| ├── index.html
| ├── logo.svg
| ├── manifest.json
| ├── search-stopwords.json
| ├── styles
| ├── toc.html
| └── xrefmap.yml
└── _site_pdf
├── docfx_project.json
├── docfx_project_pdf.pdf
└── _raw

directory: 14 file: 157

ignored

欢迎关注我的其它发布渠道