入門乾貨之用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六、結尾

　　　　

　　　　各位，這東西多而雜，如有遺漏請知乎一聲。

　　　　歡迎你們在飛雪或連天羣裏進行討論和補充，感謝各位。