微软文档生成工具 docfx 学习笔记（一）

参考链接：

DocFX - static documentation generator | DocFX website

docfx 做一个和微软一样的文档平台

一、安装

下载DocFX安装包。下载

解压压缩包之后，添加路径至环境变量。

二、简单使用

新建一个文件夹 temp_docfx 作为临时用文件夹，进入文件夹，初始化一个 DocFX 项目。-o 参数指定生成项目的输出路径。

cd .\temp_docfx
docfx init -q -o LittleBlog.Docs

文件夹结构

生成项目，构建website。

cd LittleBlog.Docs
docfx .\docfx.json

运行website。

docfx serve .\_site

查看效果。  

三、进阶-添加代码文档

生成代码的元数据添加到DocFX项目中。

进入代码项目目录，指定*.sln文件为元数据生成的目标，*.csproj文件也可以是生成的目标。

docfx metadata ./LittleBlog.sln

完成后将目录下 _api 文件夹内所有内容复制到 LittleBlog.Docs 下的 api目录内。

修改 LittleBlog.Docs 目录下的 toc.yml 文件，如下所示。

- name: Articles
  href: articles/
- name: Api Documentation
  href: api/

重新构建一下 LittleBlog.Docs 的 website。

docfx .\docfx.json

运行一下，看下效果。

docfx serve .\_site\

四、进阶-添加代码文档（使用docfx.json配置文件）

在上面（三）中，程序源代码和 DocFX 项目不在一个目录中，所以先在源代码的目录下生成元数据文件然后拷贝到 DocFX 项目内，这样比较繁琐，我们可以在 docfx.json 的文件中配置一下，然后在 DocFX 的木来执行命令即可。

这一做法有两种情况：

1、将源代码放在 DocFX 项目下的 src 目录中。此时配置文件如下所示：

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

files 指的是目标文件，可以是 *.sln 或者 *.csproj 文件。exclude 指的是排除的文件夹。

2、源代码没有放在 src 文件夹内，在 DocFX 之外，这个时候需要使用 src 属性指定到源代码的文件夹，如下所示：

"metadata": [
    {
      "src": [
        {
          "src": "../../LittleBlog/",
          "files": [
            "**.sln"
          ]
        }
      ],
      "dest": "api",
      "disableGitFeatures": false,
      "disableDefaultFilter": false
    }
  ]

项目解决方案文件在 LittleBlog文件夹下，所以 src 属性定位到 ../../LittleBlog 文件夹，然后文件 files 指定为 **.sln。

如上完成配置文件后，在 DocFX项目下执行 docfx metadata 命令即可完成生成元数据。