20190131 经验总结：如何从rst文件编译出自己的sqlalchemy的文档
20190131 经验总结：如何编译sqlalchemy的文档
起因
www.sqlalchemy.org官网上不去了，不管是直接上，还是用代理都不行。
sqlalchemy属于常用工具，看不到官方的文档很不方便。
方法
源码路径
在github上找到sqlalchemy的官方地址，这里有文档的源码，位于路径：sqlalchemy\doc\build，文档源码文件格式是rst，这是python的标准文档格式，要转换为html，
如何打开rst文件
参考了这篇网文 RST文件打开 ，了解到需要借助于sphinx，所以打算用pip安装相关环境
在创建好环境之后，只要使用sphinx-build build doc来编译就可以
创建虚拟环境
- 进入到sqlalchemy\doc目录
- pipenv install，创建虚拟环境
- 使用pipenv shell 进入虚拟环境
- 在doc目录下再创建doc目录，和build平级
错误安装
- pip install sphinx
- pip install changelog
- pip install sphinx-paramlinks
- pip install zzzeeksphinx
由于pypi上面的几个插件库的版本和sphinx不一致，所以接下来使用 sphinx-build build doc来编译时，会报错。主要就是zzzeeksphinx内部引用sphinx的各种路径出错，所以我猜是版本不匹配
正确的安装
既然上面的不行，所以使用pip uninstall 卸载到3个插件。
然后看到doc\build有个 requirements.txt文件，猜是可以直接从源码来安装这个3个插件。
所以，在虚拟环境下进入到 doc\build 目录，然后执行：
- pip install -r requirements.txt
安装插件成功
然后再回到doc目录下，使用 sphinx-build build doc来编译，成功。
