基于 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