微軟開源全新的文檔生成工具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下運行。