入门干货之用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/

我用的是旧版(相比于前两天的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工程里进行本地添加引用。

  • 发表于:
  • 原文链接:http://kuaibao.qq.com/s/20180116B02POY00?refer=cp_1026

同媒体快讯

相关快讯

扫码关注云+社区