DocFx生成Asp.NetCore文档

前言

在看微软官方文档的时候,提到”To build the API Browser, we used open standards and tools. At its core, we leveraged DocFX - the open documentation generation toolchain, along with Xamarin’s mdoc application.”
微软的.Net文档是通过DocFx来生成,通过该工具,可以在本地内网容器环境搭建Asp.Net Core的文档。

DocFx

1、下载DocFx(github releases),windows系统设置环境变量
2、执行命令,生成一个初始化的dockfx项目

1
docfx init -q

3、将本地nuget仓库中的Asp.Net Core源码源码dll和对应xml文件,拷贝到上述生成的项目的src目录中
4、需要修改docfx.json为元数据目标文件为:src/**/*.dll。
4、执行命令,构建API文档。docfx.json可以设置默认的icon、logo、模板等信息。
1
docfx docfx_project\docfx.json 

备注

1、直接将源码中的src拷贝到项目的src目录,通过docfx.json修改配置为”src/**/*.sln”进行构建会导致问题,问题:标签不能正确链接指向跨解决方案的类,可能是未经过nuget restore。
2、为了避免上述问题,可以直接从nuget本地源中将Asp.Net Core的dll和dll对应的xml文件,拷贝到docfx项目的src中。
3、修改docfx.json中的”metadata”配置,将”src”下的”files”改成”src/**/*.dll”即可。
4、docfx.json中的template配置,默认是default,可以切换成statictoc,statictoc比default生成的文件大,因为每个生成的html文件都包含了toc搜索的内容,而default模板打包出来的是单独加载toc.html的文件,这就导致页面在切换的时候会出现闪动的情况。