Sphinx+RTD+Github搭建learn

提示

本篇文档将按步骤教你如何从零搭建开始搭建一个在线技术文档。

快速搭建Sphinx之基础准备

安装python

由于sphinx依赖于python，所以我们需要先安装python

• 点击随指引安装python install Python
• 添加python和pip的环境变量

安装sphinx并且快速构建一个文档

• cmd安装sphinx

```bash

pip install sphinx

```

• 接着在cmd进行如下操作，建立sphinx框架文档

• 可以看到文件夹下面已经初始好了基本文件

• 在有make.bat的文件目录下，构建sphinx快速开始预设的的基础文档

• 构建好的静态页面就是这个index.html。有了本地构建，我们就能在每次写完文档上传前查看效果

接下来我们对sphinx的所有配置更改都位于conf.py这个文件

配置文件修改

1.更改样式

• 将原本的’alabaster’替换成’sphinx_rtd_theme’

• 再次`make html`构建文档，可见样式和learn一样了

2.添加两行代码，确保后续构建没问题

```bash

source_suffix = [‘.rst’, ‘.md’] master_doc = ‘index’

```

快速了解文档规则

文档的编写默认是支持reStructuredText语言，也可以通过加载插件的方式支持markdown，但我个人推荐使用reStructuredText，因为它的使用更灵活，方式更多样,但同时也比较复杂。` 语法参照 syntax

文档内容放置在source/文件夹下即可，文档的入口是index.rst(也就是说打开文档右侧显示的内容就是index.rst，与此同时左侧的目录也是由index.rst文件中配置生成，具体可以参照本文档的github)。 其次是在index.rst中我们也可以嵌套其他的index.rst，但他们不能位于同一个目录级。

使用Markdown来编写文档

由于Sphinx默认的是.rst，使用Markdown则需要扩展支持

1.首先使用cmd本地安装

    pip install recommonmark

2.在conf.py配置文件中加入这个扩展

3.此时你就可以使用markdown进行编写了。当你第一次新增了markdown页面时，先在make.bat文件目录下使用make clean清除_build里的构建内容，再重新make html构建一次观察效果

需要注意的是，md的语法和rst有很大差别，在sphinx中，用rst来编写会更完美

Github托管代码

1.首先，在github创建一个仓库，与本地文件夹的同名即可，创建一个空仓库，根据命令提示进行下面操作

2.安装git，参照安装教程

3.在根目录下新建一个文件取名.gitignore,打开，填入如下内容

# sphinx build folder
build

本地的build是无须被上传的，所以我们直接push时忽略掉。

3.安装git成功后，我们来到文件夹的根目录，右键空白处，可见并选择Git Bash Here，随之弹出终端。根据第1步中的提示操作注意敲入命令使本地和远程仓库连接并推送。

导入ReadtheDocs并建立钩子

1.前往ReadtheDocs页面，并注册账号 https://readthedocs.org/

2.登录并进入我们的项目，选择Import a Project => 手动导入

3.填入项目名字，代码链接使用

4.进入管理页面，在下方语选择繁体，并Save

5.再次进入管理=>集成=>添加集成=>集成类型默认Github进向webhook=>添加集成。复制这个链接

6.在github仓库可见webhook已经自动连接成功。

7.每次更新仓库，都会自动触发构建，时间随内容量几分钟到几十分钟不等。

8.到这里已经成功了，我们通过概况下的网址已可以搜索到在线文档了。 接下来若想要更改域名，只需要购买域名，并在管理=>域中设置。