Docfx 工具

简介

DocFx 是微软推出的一款开源的、可扩展的静态文档生成工具，可以通过 DocFx 创建技术型文档网站。 DocFx 可以从源代码中提取注释生成文档，使您可以非常轻松地生成具有登录页面、API 参考和概念文档的开发人员中心。

我们通过 DocFx 工具提取 git 仓库下 doc 文件夹下面的资源，通过 DocFx 提供的 toc.yml 配置文件自定义目录结构生成预期的 srs 及其它相关文档的网页站点。

文档的编写人员只需要致力于在仓库中进行文档的编写工作，签入后我们可以通过 DocFx 和持续集成工具自动完成文档的及时发布。

参考 ：https://dotnet.github.io/docfx/

github : https://github.com/dotnet/docfx

使用

具体如何使用请参见官方文档：https://dotnet.github.io/docfx/

公司的研发文档会结合模板使用， 本文着重说下注意点：

docfx.json文件相关

具体模板见：https://github.com/weihong-phoenix/DevDocContribute/blob/main/docfx.json build/template节点：除了添加默认的（default）， 还需要增加我们自定义模板的路径（相对docfx.json文件）。 pdf/template节点： 他的默认模板为pdf.default。

运行相关

前置条件： 安装 choco 工具， 参考这里

Step 1: 安装docfx

choco install docfx

Step 2: 编译站点 切换当前目录到仓库根目录

docfx build

Note

由于mermaid的展示及pdf导出需要使用到plugin， 当您运行docfx build时， 可能会提示目录没有权限。 这时， 需要将终端采用管理员运行即可。

Step 3: 运行web服务 切换当前目录到仓库根目录。 该命令仅仅将_site目录作为web站点发布。

docfx serve _site

Step 4: 打开浏览器， 输入：http://localhost:8080/