如何制作一本在线的电子书或 Python 文档供其他人远程访问

可能你有时候会看到这样的文档和在线电子书：

如果你自己想要写一个类似这样的电子书或者文档，并且直接托管到线上，应该怎么操作呢？

这时候我们可以使用 read the doc，它开源免费，并且可以使用到 Github 的 webhook， 也就是说，当你将你的生成的文档或者电子书托管到 GitHub 之后，就可以和 read the doc 进行关联，这样当你每次更新 push 到 GitHub ，read the doc 显示你的在线文档也会跟着一起更新渲染，简直太方便了。

接下来我给你演示一下，如何生成和部署。

首先确保你安装了 sphinx ，如果不知道 sphinx 如何操作可以自行搜索一番，我这里就直接用命令来进行演示了。

首先创建一个目录并进入：

使用 sphinx-quickstart 命令，创建必要的配置文件：

完事之后你的目录下就生成了这么些文件：

进入 source ，创建一个 md 文件（你用 rst 也可以，只不过我习惯用 markdown ）：

假设你的内容如下：

想要 sphinx 支持 markdown ，需要安装 recommonmark

pip3 install recommonmark:

接着修改下 conf.py:

接着我们再安装 rtd 主题

pip install sphinx_rtd_theme：

修改 conf.py， 将 theme 修改为 rtd：

接着在 index.rst 中添加文件索引：

保存退出，到 handsomeb 目录中 make html：

完事之后你的 build 目录下就生成了 html 文件了，打开 index 看看：

这样一本电子书就完成了，现在有两种方式供别人访问：

1、自己扔到自己的服务器上

2、托管到 Github 和 read the doc 关联。

第一种方式太简单了，上传文件到 webserver 即可，就不多说了，我们来看看如何托管到 Github 和 read the doc 关联。

首先在你的 Github 创建一个仓库：

然后把文件 push 上去：

可以看到你的 GitHub 仓库有你刚刚 build 的文件了：

完事之后，进入这个网站注册一个账户：

https://readthedocs.org/

你可以直接使用 GitHub 登录，然后 import 项目：

也可以手动导入，把你刚刚的的 Git 地址填进去：

然后它就会开始去 hook 你的项目，构建文档：

接着就可以让大家在线访问了：

下次你要更新你的文档，只需要直接在本地更新完 push 到 Github 上面去可以了，是不是很 nice 咧？