手把手教你给项目添加文档
- 2020 年 3 月 27 日
- 笔记
该文档主要是由Read the Docs这个在线文档托管、Sphinx这个基于Python的文档生成项目以及我们常逛的人类精华宝库GitHub实现的，下面我们就来梳理一下如何生成文档。
创建仓库
首先，我们需要在GitHub上创建仓库并将该仓库克隆到本地，当然你也可以直接在原有仓库上进行操作。
注册账号并连接到GitHub
接着我们需要在ReadtheDocs官网注册一个账号，https://readthedocs.org/ ，注册成功后在设置中选择已连接的服务，并点击Connect to GitHub按钮。
项目导入
在个人面板点击Import a Project，选择需要创建文档的项目，若是未找到目标项目，可以点击右上角的刷新并等待。
构建文档
导入项目之后，我们点击Build version即可成功创建文档
等待片刻后即可构建完成，Webhook自动添加之后只要更新GitHub仓库，项目文档就会自动重新构建。
然后我们就能够看到文档的雏形
添加文档
在做完上述前期工作之后，我们要来动手书写自己的文档。首先，我们需要安装Sphinx(速度较慢，建议切换成清华镜像下载)，
pip install sphinx sphinx-autobuild sphinx_rtd_theme pip install sphinx sphinx-autobuild sphinx_rtd_theme -i https://pypi.tuna.tsinghua.edu.cn/simple
接着我们进入到本地仓库目录，进行初始化，
sphinx-quickstart
可以通过一直回车来使用默认配置，在这里我主要选择了source和build目录分离，并且使用中文为项目语言。
Separate source and build directories (y/n) [n]:y Project language [en]: zh_CN
然后我们可以通过修改source/conf.py文件来更改文档主题并添加markdown文件的支持(需要安装recommonmark)。
import sphinx_rtd_theme html_theme = "sphinx_rtd_theme" html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] from recommonmark.parser import CommonMarkParser source_parsers = { '.md': CommonMarkParser, } source_suffix = ['.rst', '.md']
我们可以通过在项目根目录执行下述命令在本地生成html文件
make html
并且在build/html/index.html中来预览项目文档
最后，我们只需要修改index.rst文件便可以修改文档内容，reStructuredText 是扩展名为.rst的纯文本文件，含义为"重新构建的文本"，其是轻量级标记语言的一种，被设计为容易阅读和编写的纯文本，具体如何书写可以参考下面给出的链接。
参考资料
- Quick reStructuredText：https://docutils.sourceforge.io/docs/user/rst/quickref.html
- Sphinx： https://docs.readthedocs.io/en/latest/intro/getting-started-with-sphinx.html
