docfx使用

介绍

docfx是微软的一款开源在线文档构建工具，可以用来为你的项目创建说明文档和API文档。

下载

docfx可以通过dotnet tool进行下载和更新。

1. 首先确保你已经安装了dotnet
2. 输入如下指令进行安装

dotnet tool update -g docfx

入门使用

1. 初始化文档项目模板

在想要生成文档项目的位置执行如下的指令

docfx init

2. 生成文档并尝试预览

输入如下指令

docfx docfx.json --serve

指令中的docfx是文档的配置文件，记住这个配置文件，之后的定制都需要修改它

输入如上指令后，就可以访问本机的8080端口，访问你的文档
http://localhost:8080

指定项目

打开上面生成的docfx.json文件，指定你的vs项目文件(*.sln)
在src这一节点中，配置源文件的存放路径，并配置你的项目文件名称
如下:

{
  "metadata": [
    {
      "src": [
        {
          "src": ".././",
          "files": [
            "**/*.sln"
          ]
        }
      ],
      "dest": "api",
      "filter":"./filterConfig.yml",
      "namespaceLayout":"nested",
      "memberLayout":"separatePages"
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "**/*.{md,yml}"
        ],
        "exclude": [
          "_site/**"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ]
      }
    ],
    "output": "_site",
    "template": [
      "default",
      "default(zh-cn)"
    ],
    "globalMetadata": {
      "_appName": "{Your App Name}",
      "_appTitle": "{Your App Title}",
      "_appFooter":"<span>This sites built by <a href=\"https://dotnet.github.io/docfx/index.html\">docfx</a></span>",
      "_enableSearch": true,
      "pdf": false
    }
  }
}