入門幹貨之用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工程裏進行本地添加引用。
0x05、廣告時間
0x06、結尾
各位,這東西多而雜,若有遺漏請知乎一聲。
歡迎大家在飛雪或連天群裏進行討論和補充,感謝各位。
入門幹貨之用DVG打造你的項目主頁-Docfx、Vs、Github