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

开发中，有一句话叫 最不喜欢的是写文档，最不喜欢的是看别人家代码没有文档。那么世界上文档写最 la 好 ji 的就是微软了，那么微软的api文档是如何做的？难道请了很多人去写文档？

实际上微软有工具用来生成 api 文档和教程。

我这里说的微软文档是：https://docs.microsoft.com/en-us/dotnet/articles/csharp/index 这个网站，不是以前的。

微软文档使用的工具是 docfx ，这是一个很好的工具。

本文将告诉大家如何使用这个工具做出和微软一样的文档

下载

第一步是下载，下载地址是 https://github.com/dotnet/docfx/releases 如果觉得github下载太慢，可以下载我上传的：http://download.csdn.net/detail/lindexi_gd/9839609

安装

下载之后需要解压到软件运行的文件夹，假如一般放软件的是在 E:\软件 ，就可以把他解压到这里。

假设解压到 E:\软件\docfx

在使用之前需要确定已经安装.NET Core和Microsoft .NET Framework 4.6

环境变量

因为这个软件是命令行，所以希望在任何都可以使用，添加软件到环境变量

    setx PATH "%PATH%;E:\软件\docfx\"

创建文档文件

首先创建一个文件夹，用来放临时文件

这里使用的文件夹是D:\docfx_walkthrough

然后使用cmd进入这个文件夹。

简单的方法是地址输入就好，不需要打开cmd一点进入

在cmd输入命令 docfx init -q 后面的参数是表示快速，如果希望让他问你，你自己写设置，那么就不要加参数。

输入这个命令会生成docfx_project，这里就是新建的文件，可以看到 docfx.json

这个文件就是设置文件，可以打开看一下

生成文档

现在就可以进行生成文档了，因为默认就有一些文档。

我也觉得快点让你看到这个工具如何使用才是好的，不需要做太多步就可以看到自己弄出来的网站，这个感觉一般还是很好。

在cmd输入下面命令，因为这里的 cmd 没进入 docfx_project ，路径就是这样

    docfx docfx_project/docfx.json

可以看到创建了 _site ，这里就是网页，但是本地查看网页不太好，来使用自带的方法。

查看文档

这个工具可以让你从浏览器看到自己的文档，使用方法是在cmd输入代码

    docfx serve docfx_project/_site

打开 http://localhost:8080 就可以看到网站啦。

注意，如果你的 8080 端口被占用，可以自己定义打开的哪个

    docfx serve docfx_project/_site  -p 可以用端口

添加文档

现在让我们添加自己的文档

打开 articles 文件夹，添加自己的文档，这里添加

    win10 uwp MVVM入门.md

    win10-uwp-快捷键.md

打开 articles 的 toc.yml ，把文件添加进来

- name: win10 uwp MVVM入门
  href: win10 uwp MVVM入门.md
- name: win10-uwp-快捷键
  href: win10-uwp-快捷键.md

现在已经做好啦

重复 生成文档 和 查看文档 文档两步。

首先关闭 cmd 再打开，生成文档

    docfx.exe ./docfx.json