微软开源全新的文档生成工具DocFX

微软放弃Sandcastle有些年头了,微软最近开源了全新的文档生成工具DocFX，目前支持C＃和VB，类似JSDoc或Sphinx，可以从源代码中提取注释生成文档之外，而且还有语法支持你加入其他的文件链接到API添加额外的说明，DocFX会扫描你的源代码和附加的文件为你生成一个完整的HTML模版网站，你可以自己通过模版定制，目前已经内嵌了几个模版，包括静态的HTML页面和AngularJS页面。你还可以自己定制模版，具体参考 how to create custom template。

源代码： https://github.com/dotnet/docfx

文档： http://dotnet.github.io/docfx/

• 点击“查看源文件”的API来路由到GitHub的源代码（您的API必须推送到GitHub上）
• 提供DNX版本跨平台支持。
• Visual Studio的无缝内使用docfx。 注：官方docfx.msbuild的NuGet包现在在预发布版本。您也可以使用源代码编译，并在本地使用它。
• 我们支持Docfx Flavored Markdown(DFM) 编写的文档。  DFM是Github上 Markdown（GFM），并增加了一些新的功能，包括文件包含 ， 交叉引用 ，和YAML头 100％兼容 。有关DFM详细说明，请参考DFM

 
dotnet core网站就是使用docfx生成的文档示例： dotnet core。

在docfx中，最重要的就是生成文档，把markdown文件（gfm语法）转换成html，微软还开源一个基于gfm的并且很容易扩展的语法的markdown组件 MarkdownLite，代码包含在docfx，nuget库里包的名字是Microsoft.DocAsCode.MarkdownLite。

有一篇文档详细介绍了如何使用docfx： Getting Started with docfx，具体怎么使用请看这篇文章, 这里还有个OpenLiveWriter 的例子 Use docfx to auto-generate documents for OLW。

FAQ:

Q: docfx是什么？

A: docfx是一个api文档编译软件，它能根据c#/vb源代码生成对应的文档元数据并生成文档（目前提供html），并支持普通md文件。

Q: docfx的输入和输出是什么？

A: docfx metadata需要源代码来生成文档元数据，docfx build使用文档元数据+普通md文件生成文档（html）

Q: docfx支持定制模板么？

A: 是的，可以参考文档

Q: docfx跨平台么？

A: docfx支持在dnx下运行。