入門乾貨之用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工程里進行本地添加引用。

喜歡這篇文章嗎？立刻分享出去讓更多人知道吧！