使用DocFX生成文档

文档生成工具DocFX， 类似JSDoc或Sphinx，可以从源代码中提取注释生成文档之外，而且还有语法支持你加入其他的文件链接到API添加额外的说明，DocFX会扫描你的源代码和附加的文件为你生成一个完整的HTML模版网站，你可以自己通过模版定制。

使用docfx 命令

1.下载

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

2.使用

创建初始项目

docfx init -q

此命令生成一个名为docfx_project的默认项目。

3.生成网站

docfx docfx_project\docfx.json --serve

现在你可以访问http://localhost:8080查看生成的网站。使用 -p 端口 可以指定端口。

 

API文档

将编写的项目复制到docfx_project\src 文件夹，然后生成即可。

默认为搜索项目，也可设置为解决方案，打开docfx.json 文件

  "metadata": [
    {
      "src": [
        {
          "files": [            "src/**/*.sln"
          ],
          "exclude": [
            "**/obj/**",
            "**/bin/**",
            "_site/**"
          ]
        }
      ],

"src/**/*.sln" 为遍历src 下的子文件夹里的sln文件。

REST API文档

DocFX现在支持Swagger规范版本2.0之后生成的REST API文档。

Swagger RESTful API文件必须以.json 结尾的文件。

一个Swagger API文件生成一个HTML文件。例如。文件contacts.swagger.json生成文件命名contacts.html。

在docfx_project 新建一个restapi文件夹，然后将json 文件复制进去，再新建一个toc.md 

# [API](api.json)

接着在docfx_project 文件夹下toc.yml 加一行

- name: REST API
  href: restapi/

再在docfx.json 文件中

"build": {
    "content": [
      {
        "files": [
          "api/**.yml",
          "api/index.md"
        ]
      },
      {
        "files": [
          "articles/**.md",
          "articles/**/toc.yml",
          "toc.yml",
          "*.md",          "restapi/**"
        ],
        "exclude": [
          "obj/**",
          "_site/**"
        ]
      }
    ],

加入 "restapi/**" ，重新生成访问就可以看到REST API。

最终效果图如下：

 

原文地址：http://www.cnblogs.com/linezero/p/docfx.html

---

.NET社区新闻，深度好文，微信中搜索dotNET跨平台或扫描二维码关注