NMSLanX

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

 

0x01、介绍

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

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

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

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

 

0x02、吐槽

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

    我用的是旧版(相比于前两天的release来说),入门还行,但是生成默认环境的那个地方有点不妥,不能覆盖文件夹。

 

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、结尾

    

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

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

 

    

    

相关文章: