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来编译，成功。

来自为知笔记(Wiz)