關(guān)于如何高效書寫文檔读宙，我是在完成這個(gè)項(xiàng)目中跌跌撞撞慢慢摸索彻秆，不一定很合理，但我這樣寫文檔比較舒服结闸，于是分享出來(lái)希望能有些幫助唇兑。
什么時(shí)候?qū)懳臋n？
貫穿整次更新過(guò)程桦锄。
一次更新前寫文檔扎附，畫時(shí)序圖、活動(dòng)圖结耀、狀態(tài)圖等 確認(rèn)復(fù)雜的邏輯是否合理留夜。
更新時(shí)，描述一番各個(gè)接口再去實(shí)現(xiàn)接口图甜。完成接口的開發(fā)碍粥，并寫單元測(cè)試通過(guò)后，git提交一次黑毅；
上線測(cè)試服務(wù)器嚼摩，手動(dòng)調(diào)用一次接口，有問(wèn)題返工；
完成文檔后枕面，git再提交一次愿卒。
文檔怎么寫？
寫文檔用 Sphinx
繪圖用 PlantUML:http://plantuml.com/
PlantUML官方中文文檔
怎么安裝潮秘、配置
Sphinx
$ sudo pip3 install sphinx
sphinx配置請(qǐng)參考 Sphinx 使用手冊(cè)
PlantUML
如果希望在本地生成PlantUML要配置很多東西掘猿，非常麻煩。
推薦使用 plantweb 有網(wǎng)就能用唇跨。
$ sudo pip3 install plantweb
在conf.py的extensions中添加plantweb
extensions = [....,
'plantweb.directive'
]
怎么把文檔部署到readthedocs上稠通？
首先要先注冊(cè)一個(gè)賬號(hào)... https://readthedocs.org
鏈接到你的github （p.s.這個(gè)連接已斷開是機(jī)翻...實(shí)際上這個(gè)按鈕點(diǎn)了才會(huì)斷開連接）
導(dǎo)入你的項(xiàng)目 點(diǎn)擊import a Project
這里可以看到我已經(jīng)導(dǎo)入了一個(gè)項(xiàng)目
這是我readthedocs中項(xiàng)目的配置
分支名寫new_feature是因?yàn)槲业捻?xiàng)目分支設(shè)置成了這個(gè) 一般默認(rèn)寫master就好
所需求的文件是要新建一個(gè)txt文檔 把plantweb==1.1.0放進(jìn)去就好 具體可以參見我項(xiàng)目中的這個(gè)文件
最后，我的項(xiàng)目地址是https://github.com/bllli/tsxyAssistant/tree/new_feature
文檔地址http://tsxyassistant-docs.readthedocs.io/zh_CN/latest/
一點(diǎn)個(gè)人見解买猖，難免有疏忽改橘。歡迎批評(píng)，歡迎交流玉控。
