微软开源全新的文档生成工具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 马克(Mark)down(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下运行。

相关文章