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)