查看“ReadTheDocs”的源代码

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

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

===使用webhook自动构建===


===可能遇到错误===
*docs/contents.rst not found
由于Sphinx版本不同，当前ReadTheDocs服务器上构建文档的Sphinx版本默认为Sphinx v1.8.5。以下2种解决办法：
#在conf.py文件加入 master_doc = 'index' 
#或者通过设置[https://docs.readthedocs.io/en/stable/guides/specifying-dependencies.html requirements.txt]，定义Sphinx的版本和本地一样。
{{了解更多
|[https://github.com/readthedocs/readthedocs.org/issues/2569 GitHub：readthedocs/readthedocs.org-Sphinx error]
}}
==构建过程==
ReadTheDocs构建文档过程如下：
 <nowiki>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</nowiki>


==资源==
===官网===
*[https://readthedocs.org/ ReadTheDocs 官网]


[[分类:编程工具]]