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)