入门干货之用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這個文件夾很重要，一會講?！ ?/p>
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、結尾
各位，這東西多而雜，若有遺漏請知乎一聲。
歡迎大家在飛雪或連天群里進行討論和補充，感謝各位。
原文地址:http://www.cnblogs.com/NMSLanX/p/8283878.html
.NET社區新聞，深度好文，歡迎訪問公眾號文章匯總 http://www.csharpkit.com
總結
以上是生活随笔為你收集整理的入门干货之用DVG打造你的项目主页-Docfx、Vs、Github的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 微软发布PowerShell Core第
- 下一篇： ASP.NET Core中使用IOC三部