使用readthedocs+github+sphinx+reST构建文档

直入主题：

1. 准备好文档项目

# 安装相关包
pip install --user sphinx sphinx-autobuild sphinx_rtd_theme
# 要构建的文档项目内开始执行
sphinx-quickstart
#构建html
make html
# 修改conf.py的html_theme为"sphinx_rtd_theme"，重新构建html
make html

2. 推送到github托管你的文档

3. 将托管的文档用readthedocs来展示

实现以上部分，关键在于github和readthedocs之间的消息请求实现建立，使得github的代码变动可以让readthedocs自动构建(build)并显示最新文档，具体如下：

• readthedocs端
  import a project后build version即可触发构建完成，由于readthedocs和github用户间已建立关联，该项目的url地址即刻被github访问到（这里其实readthedocs作为server被github执行POST请求其代码更新），url地址如图：

  
  
  

  readthedocs-intergrations

• github端
  如没有readthedocs的地址，手动在github加个hook。

  
  
  

  github-hook

readthedocs右下角短网站打开就可以看到了cromwell-wdl。
不错，以后每次更新文档代码都可以自动同步阅读了，很方便，后面就是多写reST了，也支持md格式。

参考：

• read the docs
• sphinx使用手册
• 如何用 ReadtheDocs、Sphinx 快速搭建写书环境