ReadTheDocs

ReadTheDocs提供免费的文档托管服务。ReadTheDocs常与GitHub和Sphinx搭配使用，构建项目文档。

使用

手动构建文档

• 登录ReadTheDocs官网
• 点击导入项目
• 填入项目地址，如：https://github.com/yourname/project.git
• 文档可以在根目录project下，也可以在docs中，ReadTheDocs会自动拉取。
• 文档修改后在ReadTheDocs中点击构建。

可能遇到错误

• docs/contents.rst not found

由于Sphinx版本不同，当前ReadTheDocs服务器上构建文档的Sphinx版本默认为Sphinx v1.8.5。以下2种解决办法：

1. 在conf.py文件加入 master_doc = 'index'
2. 或者通过设置requirements.txt，定义Sphinx的版本和本地一样。

了解更多 >> GitHub：readthedocs/readthedocs.org-Sphinx error

构建过程

ReadTheDocs构建文档过程如下：

git clone --no-single-branch --depth 50 https://github.com/yourname/project.git .
git checkout --force origin/master
git clean -d -f -f
python3.7 -mvirtualenv  /home/docs/checkouts/readthedocs.org/user_builds/yourproject/envs/latest
/home/docs/checkouts/readthedocs.org/user_builds/yourproject/envs/latest/bin/python -m pip install --upgrade --no-cache-dir pip
/home/docs/checkouts/readthedocs.org/user_builds/yourproject/envs/latest/bin/python -m pip install --upgrade --no-cache-dir Pygments==2.3.1 setuptools==41.0.1 docutils==0.14 mock==1.0.1 pillow==5.4.1 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.8.1 recommonmark==0.5.0 sphinx<2 sphinx-rtd-theme<0.5 readthedocs-sphinx-ext<1.1
cat docs/conf.py
python /home/docs/checkouts/readthedocs.org/user_builds/yourproject/envs/latest/bin/sphinx-build -T -b readthedocs -d _build/doctrees-readthedocs -D language=en . _build/html

资源

官网

• ReadTheDocs 官网