基於 Python 官方 GitHub 構建 Python 文檔

 

最近在學 Python，因此老是在看 Python 的官方文檔， https://docs.python.org/2/

由於祖傳基因的影響，我老是喜歡把這些文檔保存到本地，不過 Python 的文檔實在是太多， 根本存不過來。後來追蹤到 Python 官方的 GitHub 文檔地址， 乾脆就把官方的 GitHub 下載下來了：cpython GitHub 地址。

 

---

 

1. 下載 Python 的 GitHub 倉庫：cpython
從 GitHub 上 clone 倉庫很簡單，在命令行中執行命令 git clone git@github.com:python/cpython.git 就能夠啦。

不過由於 Python 的 cpython 倉庫比較大，一時半會兒下載不完， 我在 clone 到本地的時候出現了網絡問題，進度條卡住不動了。 根據以前的經驗，此時若是我直接 Ctrl + C 退出 clone， 那麼下載了一半的文件，就會被 git 刪除，這是很差的。

因此我選擇的是在另外一個命令窗口裏面，先把下載了一半的文件徹底 cp 一份， 而後再到卡住的窗口裏面，把正在執行的 git clone 命令給 Ctrl + C 了。

殺掉 git 命令後，ls 看當前的目錄，以前下載了一半的那些文件果真又雙叒不見了。 不過幸虧剛剛作了備份。進到備份的目錄裏面，執行 git pull 命令，竟然可以斷點續傳。這是好的。

---

 

2. 構建 Python 文檔
clone 完了 Python 的倉庫，下面就能夠構建文檔了。 要說 Python 社區作的文檔真是不錯，基本不須要複雜的操做， 就能夠把 Python 的文檔構建出來，真是不服都不行。

2.1 構建 epub 格式的文檔
作這個的目的是但願在上下班的路上，能夠在手機上方便的查看 Python 文檔， 就當看電子書了，還能學英語。

進入 cpython 項目的目錄裏面：cd cpython

由於剛剛 clone 下來，項目的目錄裏面是空的，須要咱們 checkout 一個分支出來。 能夠先看看都有哪些分支，執行命令 git branch -a

[root@fengbo cpython]$ git branch -a remotes/origin/2.7 remotes/origin/3.4 remotes/origin/3.5 remotes/origin/3.6 remotes/origin/aleaxit-patch-1 remotes/origin/master

 

由於我如今使用的是 Python2.7 ，因此執行命令 git checkout 2.7 就能夠檢出 2.7 分支的代碼啦。

檢出完成後，進入 Doc 目錄，而後執行命令 make epub 就能夠製做 epub 格式的 Python 文檔電子書了。

[root@fengbo Doc]# git checkout 2.7 Switched to branch '2.7' [root@fengbo Doc]# make epub sphinx-build -b epub -d build/doctrees -D latex_elements.papersize= . build/epub ... build succeeded. Build finished; the epub files are in build/epub.

 

構建完成後，文件會被放在 cpython/Doc/build/epub/Python.epub 的位置。

其實在構建 epub 的時候報了不少錯誤，好比缺乏 sphinx 包。 缺什麼包安裝什麼就能夠了，不會安裝的就去百度查查怎麼安裝。

epub 文件的下載地址：

連接：https://pan.baidu.com/s/1o9JJFeE 密碼：kczx

2.2 構建 html
構建 html 的用途，是創建一個本地的 Python 文檔網站，和 https://docs.python.org/2/ 同樣的那種。

構建 html 和構建 epub 同樣，也是到 cpython/Doc 裏面。 不過此次是執行命令 make html就能夠了。

[root@fengbo Doc]# make html sphinx-build -b html -d build/doctrees -D latex_elements.papersize= . build/html Running Sphinx v1.6.6 build succeeded. Build finished. The HTML pages are in build/html.

 

不過構建 html 的結果，是一個目錄 cpython/Doc/build/html，而目錄裏面就是 .html 的文件啦。

這個目錄直接就能夠做爲網站的根目錄來使用，也能夠扔到網站的某個子目錄裏面。

下面是我構建後的效果：py.fengbohello.top/2/

---

 

同步發表：https://www.fengbohello.top/archives/python-build-doc