DocFX:值得一看的文档工具

Tue 06 February 2018 / In categories tools

.Net, C Sharp

DocFX是微软出品的一款文档生成工具,虽然在StaticGen上的排名不高,但却是一款不可小觑的文档生成工具。

DocFX基于.Net Core,所以是跨平台的,在Windows, Mac, Linux都可以使用。DocFX设计的初衷是代替Sancastle,用来给C#,以及VB作为API的文档工具,可能由于这一点,导致大家对其关注度不高。在StaticGen上排名远远落后于三巨头Jekyll、Hugo和Hexo。但是抛开其作为API文档工具的初衷,DocFX是一个不错的基于Markdown的网页生成器。

以DocFX的官网教程为例子,这就是Markdown所生成的页面。上面是导航,左侧为文章浏览,右侧则是文章的章节目录。所以,DocFX默认就提供了一个较好的适合文档的模板。当然,它也支持自定的模板和插件,在模板和插件页面可以找到。如果准备生成的文件在本地浏览的话,建议使用“statictoc”模板,生成的目录是静态的。

DocFX的安装和使用也很方便,在Windows下可以用Chocolatey直接安装:

choco install doxfx

安装完之后有一个叫docfx的可执行程序供使用。

根据Get Started教程,使用下面的命令创建一个项目:

docfx init -q

然后使用下面的命令构建项目:

docfx docfx_project\docfx.json –serve

就可以在浏览器中输入http://localhost:8080查看生成的文档。

DocFX的其他值得关注的特性: - 支持DocFX-flavored Markdown,基本上兼容Github-Flavored Markdown - 支持增量构建,在项目比较大的时候很有帮助,减少每次构建的时间。这一点和其他文档生成工具不同,其他的文档工具虽然不支持增量构建,但能够实时监控文档目录的改动来调整生成的网页。虽然支持增量构建,但是DocFX不支持实时目录监测是一个遗憾,这也是目前用户对DocFX呼声最高的需求。 - 对于API文档的支持,目前只是对阵C#和Javascript,以后会增加TypeScript和Python。可能不能满足所有人的要求。

当然DocFX是开源的,你可以在Github上找到它: https://github.com/dotnet/docfx。作为C#的文档工具,DocFX和VisualStudio也有较好的集成。

(完)

Load Disqus Comments