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

因为这三项技术涉及到的要点以及内容较多，但愿你们有空能本身挖掘一下更多更深的用法。

 

0x0一、介绍

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

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

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

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

 

0x0二、吐槽

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

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

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

 

0x0三、搭建环境

　　　　一、VS，得有Github扩展。

　　　　二、有Github帐号

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

　　　　四、接下来，咱就走一种状况，尽可能能覆盖你全部的操做的状况。

　　　　

0x0四、请开始表演

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

　　　　　　

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

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

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

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

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

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

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

　　　　　　　a、

　　　　　　　b、

　　　　　　　c、

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

 

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

　　　　　　

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

　　　　

　　　　七、改文件：打开：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

 

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

　　　　

 

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

　　　　

 

　　　　十、效果：

　　　　　　

　　　　十一、其余一些高级的编辑技巧，参见makedown，另外也能够参考个人另外一个开源项目的文档，https://github.com/NMSLanX/Mellivora

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

 

0x0五、广告时间

　　　　

 

0x0六、结尾

　　　　

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

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