没文档或者文档太烂的项目是可怕的，完善易懂的文档是一个好项目的标配。

如何管理项目文档对于维护一个靠谱的项目是至关重要的。

ReadTheDocs

这是一个很常见的项目文档托管网站，支持 GitHub，GitLab，BitBucket 登录，可导入 git，svn 等项目。

Feature

  • 支持多版本文档
  • 支持多分支构建
  • 项目更新后自动重新构建
  • 可接入 Google Analytics 和广告
  • 支持自定义域名

Weakpoint

  • 仅支持用 Sphinx 生成文档
  • 构建文档的过程限制内存为 1G（这通常不是问题，但如果你有深度学习的项目且需要安装后导入代码中的文档，光是安装深度学习的包估计就超过 1G 了）

GitHub Pages

目前有很多项目都直接用 GitHub Pages 来构建文档了，也可以用来写博客，甚至一些 CS 课程也用它展示相关信息。作为一个免费的静态页面平台，跟 GitHub 集成在一起，一向不缺用户的。

Feature

  • 具有相对较高的自由度，可以自己选择文档生成工具
  • 可以自己配置 Google Analytics，生成 RSS 等
  • 可以配合 Travis 一类的工具实现文档自动部署
  • 文档跟代码放在同一平台上易于管理
  • 支持自定义域名

Weakpoint

  • 某些搜索引擎不收录 GitHub Pages 相关页面
  • 某些地区访问 GitHub Pages 可能出现问题

自动化部署

这部分需要配合 Travis CI，当然其他 CI 工具应该也有类似的功能。

我写了一个 Gist 详细介绍相关步骤，可以在这里看到 Auto-Deploying Docs （English）。

主要是网上查到的多数都是测试完用 Bash 脚本来部署的，而 Travis 推出了一个 Beta 版的 deploy 功能，非常好用，要比 Bash 脚本部署简单很多，所以就写了这么个 Gist（因为看到别人也都是写的 Gist）。

大概的流程就是申请一个个人的 GitHub Token 用来授权操作仓库，然后在 Travis 中设置成对外不可见的环境变量，或者用 Travis 的加密变量传进去，之后就可以用 Travis 的 .travis.yml 来进行部署操作了。