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
声明:未经允许禁止转载 东东东 陈煜东的博客 文章,谢谢。如经授权,转载请注明: 转载自东东东 陈煜东的博客
本文链接地址: ReadTheDocs 私有部署搭建安装 – https://www.chenyudong.com/archives/readthedocs-private-install.html
2017 年 10 月 11 日 — 19:06
遇到同样的问题了,一直卡在 构建 那块,也看不出是什么问题,头痛
2017 年 10 月 11 日 — 19:30
请教下 “最后是raise BaseException(‘eee’)二分搜索,才在网页上看到异常信息的。”
这一句具体是怎么弄的呀,真没辙了,现在,快放弃了