入门干货之用DVG打造你的项目主页-Docfx、Vs、Github

由于这三项技术涉及到的要点以及内容较多，希望大家有空能自己挖掘一下更多更深的用法。

 

0x01、介绍

　　　　VS，即VS2017以及以上版本，宇宙最好的IDE，集成了宇宙最有前景的平台，前阶段也支持了宇宙最好的语言。

　　　　Github，知名的代码/项目托管平台，不想赘述了，如果干两三年了这个都不认识，自觉转行吧，我不在文章里说什么，但你得晓得，我肯定偷偷的鄙视你了。

　　　　Docfx，类似JSDoc或Sphinx，可以从源代码中提取注释生成文档之外，而且还有语法支持你加入其他的文件链接到API添加额外的说明，DocFX会扫描你的源代码和附加的文件为你生成一个完整的HTML模版网站，你可以自己通过模版定制，目前已经内嵌了几个模版，包括静态的HTML页面和AngularJS页面。

　　　　哎呀，说白了，就是根据你的.cs 文件生成一些API，注释，首页之类的，就是说，你用吹灰之力就能免去文档的烦恼，就这码事。

 

0x02、吐槽

　　　　我觉得VS上的github插件巨难用，反正我用它上不来气儿。之前本人用惯了PC端，高端大气上档次，同时也保证了简洁清爽功能全。PC端下载地址：https://desktop.github.com/

　　　　我用的docfx是旧版(相比于前两天的release来说，新版我下载不下来，可能宇宙发生了什么大事影响到了)。

　　　　docfx生成默认环境的那个地方有点不妥，不能覆盖文件夹。

 

0x03、搭建环境

　　　　1、VS，得有Github扩展。

　　　　2、有Github账号

　　　　3、下载docfx,配置环境变量(让你的命令行能找到docfx.exe)

　　　　4、接下来，咱就走一种情况，尽量能覆盖你所有的操作的情况。

　　　　

0x04、请开始表演

　　　　1、用Github创建一个库，记得创建readme和协议，协议如果你不知道用啥就用MIT，如图。

　　　　　　

　　　　建库的方式有很多种，别再这里跟我鸡蛋挑骨头，明白咋回事就行了。

　　　　2、想尽一切办法拉到本地。

　　　　PC：你所需要的操作就是在红框里用鼠标点点点，加号-用户-clone。

　　　　VS：先登陆，登陆完了打开团队资源管理器，Path是你的库的本地路径。如果本地已经存在这个路径了，它不允许，这点我也想吐吐槽。

　　　　3、拉到本地之后，打开它，Vs里:  打开-文件-文件夹。

　　　　4、打开PM(程序包管理控制台)，在该目录下(注意你当前环境的路径位置)，敲命令: docfx init -q 这个命令是让你生成一个默认的文档编辑框架。当然了还有其他选项比如-o 和上面的操作是一个德行，虽然说可以指定目录，但是不能指定一个存在的目录。

　　　　5、你敲完了之后会有一个新的文件夹叫：“docfx_project”, 别害怕，把里面你的东西都剪切出来，放到外面(就是你clone出来的本地文件夹)，然后删掉这个docfx_project文件夹。此时你可以向Github上提交一次你的改动。

　　　　　　　a、

　　　　　　　b、

　　　　　　　c、

　　　　　　　d、提交失败的话可能服务器版本中，某些文件比你新，那你就点蓝色的同步。没有就点推送推过去。

 

　　　　6、打开一个新的VS，开始创建你的项目。注意看图！

　　　　　　

　　　　这里有个src文件夹，是它帮咱们创建的，咱们就可以把项目建在这里面。写你的接口，写你的注释，写你一切想写的方法。然后更改-提交-同步/推送。此时你应该打开了两个VS了已经。

　　　　

　　　　7、改文件：打开：docfx.json

　　　　metadata节点下：src/files的内容 改成 "src/**.cs".  这个就是寻找你的C#文件，然后帮你生成接口页面。

　　　　　　　　　　　　src/exclude的内容 添加 "docs/**"  这个就是你生成的时候，这下面的东西都排除掉，不参与生成。 之后此文件中还有挺多exclude，你也都填上，因为docs这个文件夹很重要，一会讲。　　　　

　　　　build 节点下：　　dest节点内容改成 "docs"。就是这东西把结果都放在docs文件夹里。

　　　　　　　　　　　　template节点内容也可以改成"statictoc"  使用残暴模式，不用服务器，本地双击就看到页面的那种。

　　　　其他选项可以意会，参考文档见:http://dotnet.github.io/docfx/tutorial/docfx_getting_started.html

 

　　　　8、生成：PM里敲: docfx .\docfx.json --server ，然后去docs 文件夹里看看效果：

　　　　

 

　　　　9、配置Github,  当前代码库的页面上面有个Setting-往下拉找到Github Page-选那个带有docs的选项，然后save，然后记录一下地址。你以后发布用。

　　　　

 

　　　　10、效果：

　　　　　　

　　　　11、其他一些高级的编辑技巧，参见makedown，另外也可以参考我的另一个开源项目的文档，https://github.com/NMSLanX/Mellivora

　　　　　　注：Github库里的文件图片可能在你发布的项目主页上引用不到，请直接在你的docfx工程里进行本地添加引用。

 

0x05、广告时间

　　　　

 

0x06、结尾

　　　　

　　　　各位，这东西多而杂，若有遗漏请知乎一声。

　　　　欢迎大家在飞雪或连天群里进行讨论和补充，感谢各位。