当开源项目的内容比较多、比较杂的时候，就需要将一些说明性的东西、如教程、文档等东西从README.md文件中剥离出来搞一个文档，许多项目都是如此，于是自己也简单学了一下使用ReadtheDocs。
步骤
1.从ReadtheDocs官网注册账号并连接到Github
ReadtheDocs官网地址：首页 | Read the Docs
在注册成功后在设置->已连接的服务中点击Connect to Github：
2.在Github上创建一个项目，如test-cookbook，并将其克隆到本地。
3.安装Sphinx
pip install sphinx
4.创建工程
将路径切换到项目根目录下，执行以下命令：
sphinx-quickstart
5.对工程进程配置
项目的配置，主要是更改source/conf.py文件。
5.1 更改主题
在项目中更改或添加以下代码
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
5.2 添加markdown支持
首先安装recommonmark
pip install recommonmark
并在项目中增加以下代码
from recommonmark.parser import CommonMarkParser
source_parsers = {
'.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']
6.导入到ReadtheDocs
在ReadtheDocs个人面板点击Import a Project：
然后选择对应的项目，如果项目列表为空或者未显示当前项目，点击右上角等待刷新项目即可：
之后可以对项目进行一些设置，如图：
7.向工程中添加实际教程和文档
如新建.rst或.md文件，并修改项目的index.rst等，具体请参考最后的参考链接。
8.生成文档
在项目根目录执行
make html
以生成html格式的文档。
可能在生成文档会失败，如遇到Sphinx error: master file [..]/checkouts/latest/contents.rst not found这样的错误，可以参考Sphinx error: master file [..]/checkouts/latest/contents.rst not found · Issue #2569 · readthedocs/readthedocs.org来解决。
9.预览效果
进入build/html目录下用浏览器打开其中的index.html来预览项目文档。如：
10.push到Github仓库
三连git：
git add .
git commit -m "update cookbook"
git push
11.查看在线效果
在ReadtheDocs的项目主页点击阅读文档以查看实际效果：
效果如：
参考
- 如何用 ReadtheDocs、Sphinx 快速搭建写书环境 - 简书
- 使用ReadtheDocs托管文档 | 飞污熊博客
- Sphinx error: master file [..]/checkouts/latest/contents.rst not found · Issue #2569 · readthedocs/readthedocs.org
