使用ReadtheDocs给项目添加教程文档

 

当开源项目的内容比较多、比较杂的时候,就需要将一些说明性的东西、如教程、文档等东西从README.md文件中剥离出来搞一个文档,许多项目都是如此,于是自己也简单学了一下使用ReadtheDocs。

步骤

1.从ReadtheDocs官网注册账号并连接到Github

ReadtheDocs官网地址:首页 | Read the Docs

在注册成功后在设置->已连接的服务中点击Connect to Github
la76ts.jpg

2.在Github上创建一个项目,如test-cookbook,并将其克隆到本地。

3.安装Sphinx

1
pip install sphinx

4.创建工程

将路径切换到项目根目录下,执行以下命令:

1
sphinx-quickstart

5.对工程进程配置

项目的配置,主要是更改source/conf.py文件。

5.1 更改主题

在项目中更改或添加以下代码

1
2
3
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

5.2 添加markdown支持

首先安装recommonmark

1
pip install recommonmark

并在项目中增加以下代码

1
2
3
4
5
from recommonmark.parser import CommonMarkParser
source_parsers = {
'.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']

6.导入到ReadtheDocs

在ReadtheDocs个人面板点击Import a Project
la7BnS.jpg
然后选择对应的项目,如果项目列表为空或者未显示当前项目,点击右上角等待刷新项目即可:

la7fXT.jpg

之后可以对项目进行一些设置,如图:

la7HhR.jpg

7.向工程中添加实际教程和文档

如新建.rst.md文件,并修改项目的index.rst等,具体请参考最后的参考链接。

8.生成文档

在项目根目录执行

1
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来预览项目文档。如:
la7vnO.jpg

10.push到Github仓库

三连git

1
2
3
git add .
git commit -m "update cookbook"
git push

11.查看在线效果

在ReadtheDocs的项目主页点击阅读文档以查看实际效果:
laHF3t.jpg

效果如:
laHpAH.jpg

参考