Sphinx + GitHub + ReadtheDocs Build Wiki(使用 Sphinx + GitHub + ReadtheDocs 建立个人Wiki)

1 minute read

Published:

Sphinx 是一个基于ReStructuredText的文档生成工具,可以令人轻松的撰写出清晰且优美的文档, 由Georg Brandl在BSD许可证下开发。新版的Python文档就是由Sphinx生成的,并且它已成为Python项目首选的文档工具,同时它对C/C++项目也有很好的支持;并计划对其它开发语言添加特殊支持。
Read the Docs是一个在线文档托管服务,可以从各种版本控制系统中导入文档。支持webhooks,当你提交代码时,文档将被自动构建。
Sphinx + GitHub + ReadtheDocs 作为一个文档写作工具, 用Sphinx生成文档,GitHub托管文档,再导入到 ReadtheDocs。我们可以使用这个工具写文档、记笔记等。
我其实一直想做一个wiki,但是由于种种原因耽搁了下来,上次看到conda的document觉得还不错就下定决心花时间搭建起来。搭建中也参考了很多其他的博客,下面记录我在Ubuntu下的搭建过程。

安装 Sphinx

$ conda create -n mywiki
$ source activate mywiki
$ pip install sphinx

创建wiki目录

使用 sphinx 自带的配置工具 sphinx-quickstart 快速创建工程。

$ mkdir mywiki
$ sphinx-quickstart  //大部分情况可以直接选择默认选项,回车即可


创建完成后,mywiki目录将会出现以下文件:

  • build目录:运行make html命令后,生成的文件都在这个目录里面
  • source目录:放置文档的源文件
  • make.bat:批处理命令
  • Makefile ```Vim $ ls build make.bat Makefile source $ make html Running Sphinx v1.6.6 …… build succeeded.

Build finished. The HTML pages are in build/html.

### 修改配置文件`conf.py `
conf.py 文件包含了 Sphinx 工程的所有配置选项,包括一些无法在 sphinx-quickstart 中进行设置的。
<br>把 `conf.py` 里面的:
`html_theme = 'alabaster'`
换成
`html_theme = 'sphinx_rtd_theme'`

### 使用 github 进行版本控制
首先在 github 创建新的仓库 mywiki,然后将本地的 mywiki 目录 push 到 Github 上 mywiki 仓库。
```Vim
$ echo "# mywiki" >> README.md
$ git init
$ git add .
$ git commit -m "Initial"
$ git remote add origin [email protected]:yourusename/mywiki.git
$ git push -u origin master

导入到 ReadtheDocs

首先到 github 中选择 mywiki 仓库,依次选择Settings / Integrations & services / Add Service,然后输入ReadTheDocs,Activate即可。

然后到 ReadtheDocs 网站 import mywiki 仓库,如果你的 ReadtheDocs 和Github关联起来了,那么可以直接选择导入,或者选择手动导入也可以,导入成功后可看到如下页面: ReadtheDocs

构建文档

现在 mywiki 目录只有默认内容,需要我们自己添加内容,然后构建。构建方式有两种:

  • 命令行执行 make html
  • ReadtheDocs 网站手动构建

我们选择命令行构建这种方式,因为以后每次进行wiki的书写时,可以直接在本地先make html,再用git与你的wiki仓库同步,非常方便。

绑定二级域名

一般自己的博客都用一个域名,而 ReadtheDocs 官方生成的域名过长,不是很好记,所以我们可以用自己的二级域名,也就是自己的域名前缀加上一个wiki。
我用的是 Cloudflare 进行域名解析。进入DNS后,添加一条记录即可。 Type设置为CNAME,Name设置为wiki,Value设置为 ReadtheDocs 为你生成的域名即可。如下图所示: ReadtheDocs cloudflare

其他

reStructureText 语法很简单,不建议刻意去学,如果习惯用 Markdown,建议用 pandoc 一键转化即可.

最后,欢迎访问我的wiki: https://zhangkaiyuan.readthedocs.io/ :)

参考文献

[1] Read The Docs
[2] Sphinx 使用手册
[3] 使用sphinx记笔记
[4] 使用Sphinx + GitHub + Read the Docs搭建wiki
[5] 如何用 ReadtheDocs、Sphinx 快速搭建写书环境

Leave a Comment