东东东 陈煜东的博客

readthedocs 这个网站还真不错，提供了文档托管服务，让很多开源项目的文档变得很完善。

网上很少有Read The Docs 的一些私有部署文章，希望这篇《Read The Docs 私有部署安装》能帮助到大家，也一起交流交流。

想到有一些私有项目，目前还达不到开源的标准，但内部需要有一个文档服务，之前是利用 Nginx + Sphinx 搭建简单的 HTML 网页来展示的，缺少一些版本的控制，因此想引入 Read The Docs 开源版来进行部署。

很棒的是 Read The Docs（下文会有 RTD 来进行缩写） 提供开源的版本，官方也有一些部署的文档，但是只能说马马虎虎，会遇到一些和想象中不那么美好的事情，这里记录一下，给大家填填坑。

安装

一些步骤参考官方的网页https://docs.readthedocs.io/en/latest/install.html。

其中说一个很重要的步骤就是

virtualenv rtd
cd rtd
source bin/activate

因为 Read The Docs 会使用大量的 Python 类库，所以这里建议单独独立出一个环境来，当然也可以用 Docker 版本。

我这就出现了 RTD 的 docker-py 和 系统的 docker-compose 冲突的情况。

  File "/root/readthedocs/readthedocs.org/readthedocs/doc_builder/environments.py", line 16, in <module>
    from docker import Client
ImportError: cannot import name Client

HTTP 网络代理

这里是处理起来耗费了大量的时间的。个人不懂 Django，想打印一些日志也好不难，设置了一些 DEBUG 级别，也没有遇到想要的一些日志。

由于机器没有直接的外网访问权限，因此需要配置 http 代理，这里有说明 简单的 http 代理设置。

还有需要拉取 git 代码，git的代码也是需要使用代理的。

git clone http://github.com/sphinx/sphinx
fatal: The remote end hung up unexpectedly
fatal: early EOF
fatal: index-pack failed

网上说是git config --global http.postBuffer 524288000，可以我这一直没有成功，我一直在想我是不是我使用的代理有问题，后来换成一个 Squid 的代理 是没有出现了。

艰辛的调试过程

以前网页一直是已触发构建状态，就是一直没有看到什么失败的信息啊，也不动，心里着急，一直尝试了很久了的，都放弃了。

看到日志，加一些日志都不出现，最后是raise BaseException('eee')二分搜索，才在网页上看到异常信息的。

触发编译文档

利用异常，然后发现了报错的地方，居然都是因为服务要进行一次 HTTP 服务，被设置了代理，无法访问，所以把域名给排除代理了。不过此时的编译是阻塞型的，网页无法快速返回。接下来就是要看看要怎么异步，都已经配置了 Celery 的信息了。终于看到编译过程的真身了，兴奋不已，离成功已经不远了。

构建成功

Celery 异步触发构建

一直寻找为什么 Celery 没有异步起作用，直到根据代码一层一层深入 Celery，发现有个很重要的变量CELERY_ALWAYS_EAGER。

"""
If the :setting:`CELERY_ALWAYS_EAGER` setting is set, it will
        be replaced by a local :func:`apply` call instead.
"""
app = self._get_app()
if app.conf.CELERY_ALWAYS_EAGER:
    return self.apply(args, kwargs, task_id=task_id or uuid(),
                      link=link, link_error=link_error, **options)

之前就一直注意到EAGER这个配置，上网搜索信息，还以为是语法糖效果呢，可以不用显示的使用task.delay()。现在看注释才明白，CELERY_ALWAYS_EAGER如果为True，那么 Celery 不会使用异步模式，而是在本地上下文采用阻塞执行，所以要使用异步执行，那么需要将这个值设置为CELERY_ALWAYS_EAGER = False

配置完 redis 的信息，然后执行一些命令。

C_FORCE_ROOT=1 ./manage.py celeryd -E --loglevel=DEBUG   # 启动 Celery Worker   
./manage.py celerybeat  --verbosity=3   # 启动 Celery 周期任务事件
./manage.py celerycam                   # celery快照？

运行正常

为成果庆祝一下。

构建成功

周期任务

待补充

Docker 编译环境

待补充

相关文章

• 搭建私有git托管仓库
• https://hub.docker.com/r/moul/readthedocs/
• http://www.slideshare.net/idangazit/an-introduction-to-celery/
• http://www.slideshare.net/matclayton/django-celery
• http://www.slideshare.net/tarequeh/life-in-a-queue-using-message-queue-with-django
• https://github.com/duoduo369/skill_issues/blob/master/python/celery.issue.md

打赏