写文档？用Sphinx + PlantUML + readthedocs

关于如何高效书写文档，我是在完成这个项目中跌跌撞撞慢慢摸索，不一定很合理，但我这样写文档比较舒服，于是分享出来希望能有些帮助。

什么时候写文档？

贯穿整次更新过程。
一次更新前写文档，画时序图、活动图、状态图等 确认复杂的逻辑是否合理。
更新时，描述一番各个接口再去实现接口。完成接口的开发，并写单元测试通过后，git提交一次；
上线测试服务器，手动调用一次接口，有问题返工；
完成文档后，git再提交一次。

文档怎么写？

写文档用 Sphinx
绘图用 PlantUML:http://plantuml.com/
PlantUML官方中文文档

怎么安装、配置

Sphinx

$ sudo pip3 install sphinx
sphinx配置请参考 Sphinx 使用手册

PlantUML

如果希望在本地生成PlantUML要配置很多东西，非常麻烦。
推荐使用 plantweb 有网就能用。
$ sudo pip3 install plantweb

在conf.py的extensions中添加plantweb

extensions = [....,
      'plantweb.directive'
]

怎么把文档部署到readthedocs上？

首先要先注册一个账号... https://readthedocs.org

链接到你的github （p.s.这个连接已断开是机翻...实际上这个按钮点了才会断开连接）

readthedocs connect github.png

导入你的项目 点击import a Project

点击导入项目.png

这里可以看到我已经导入了一个项目

我已经导入了.png

这是我readthedocs中项目的配置
分支名写new_feature是因为我的项目分支设置成了这个 一般默认写master就好
所需求的文件是要新建一个txt文档 把plantweb==1.1.0放进去就好 具体可以参见我项目中的这个文件

项目配置.png

最后，我的项目地址是https://github.com/bllli/tsxyAssistant/tree/new_feature
文档地址http://tsxyassistant-docs.readthedocs.io/zh_CN/latest/

一点个人见解，难免有疏忽。欢迎批评，欢迎交流。