入门干货之用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工程里进行本地添加引用。

本文来自企鹅号 - dotNET跨平台媒体

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏北京马哥教育

让“懒惰” Linux 运维工程师事半功倍的 10 个关键技巧!

好的Linux运维工程师区分在效率上。如果一位高效的Linux运维工程师能在 10 分钟内完成一件他人需要 2 个小时才能完成的任务,那么他应该受到奖励(得到更...

4006
来自专栏程序员笔记

开发一个可维护的程序

1754
来自专栏北京马哥教育

IBM技术专家教你“懒惰”Linux管理员的10个关键技巧

作者:Vallard Benincosa, 来源: https://www.ibm.com/developerworks/cn/linux/l-10sysadt...

3035
来自专栏linux、Python学习

IBM技术专家教你“懒惰”Linux管理员的10个关键技巧

好的系统管理员区分在效率上。如果一位高效的系统管理员能在 10 分钟内完成一件他人需要 2 个小时才能完成的任务,那么他应该受到奖励(得到更多报酬),因为他为公...

920
来自专栏数据和云

数据库高可用和分区解决方案-MongoDB 篇

许春植(Luocs) (阿里巴巴高级数据库管理员,7年以上数据库运维管理经验,擅长MySQL、Oracle及MongoDB数据库,目前主要研究并建设Mongo...

8476
来自专栏Java后端技术栈

记一次解决业务系统生产环境宕机问题!

Zabbix告警生产环境应用shutdown,通过堡垒机登入生产环境,查看应用容器进程,并发现没有该业务应用的相应进程,第一感觉进程在某些条件下被系统杀死了,然...

881
来自专栏linux驱动个人学习

调度器增强

到目前为止,我们只考虑了实时系统上的调度。事实上, Linux可以做得更好些。除了支持多个CPU之外,内核也提供其他几种与调度相关的增强功能,在以后几节里会论述...

1101
来自专栏SeanCheney的专栏

《Python分布式计算》 第5章 云平台部署Python (Distributed Computing with Python)云计算和AWS创建AWS账户创建一个EC2实例使用Amazon S3存

上一章介绍了创建Python分布式应用的Celery和其它工具。我们学习了不同的分布式计算架构:分布任务队列和分布对象。然而,还有一个课题没有涉及。这就时在多台...

3586
来自专栏企鹅号快讯

11个让你吃惊的Linux终端命令

我已经用了十年的linux了,通过今天这篇文章我将向大家展示一系列的命令、工具和技巧,我希望一开始就有人告诉我这些,而不是曾在我成长道路上绊住我。 ? 1. 命...

2309
来自专栏杨建荣的学习笔记

Oracle闪回原理-Logminer解读redo(r11笔记第17天)

说到闪回日志,我们都知道闪回日志中记录的都是逆操作,那么就有两个问题需要解释了。 闪回日志和回滚段保存的数据有什么差别? 如果做了truncate操作,闪回日志...

37512

扫码关注云+社区

领取腾讯云代金券