Read the Docs是一个在线文档托管服务， 你可以从各种版本控制系统中导入文档，如果你使用webhooks， 那么每次提交代码后可以自动构建并上传至readthedocs网站，非常方便。
搭建ReadtheDocs Wiki文档
Linux
一、ReadtheDocs介绍
首先说一下这款wiki的一个发布流程 Sphinx + GitHub + ReadtheDocs 作为一个文档写作工具，利用pandoc文本转换， 用Sphinx生成文档，GitHub托管文档，再导入到 ReadtheDocs。我们可以使用这个工具写文档、记笔记等。
Sphinx
Sphinx是一个功能强大的文档生成器，具有许多用于编写技术文档的强大功能，包括：
生成网页，可打印的PDF，电子阅读器的文档（ePub），以及更多来自相同来源的文档
您可以使用reStructuredText或Markdown 编写文档 广泛的交叉引用代码和文档系统 语法突出显示了代码示例 充满活力的第一方和第三方扩展生态系统
我们这里只是讲了怎么写文章，其他的功能目前没有使用。也用不到
项目地址：https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
这里先放两张效果图，各位看官在看是否要搭建
二、环境安装
环境说明
环境不一致可能会导致导入Python包出错 CentOS Linux release 7.6.1810 (Core) Python 2.7.5 [2.6不支持] pip 1.5.4>
Pip环境安装
1.下载pip源码包 wget "https://pypi.python.org/packages/source/p/pip/pip-1.5.4.tar.gz#md5=834b2904f92d46aaa333267fb1c922bb" --no-check-certificate 2.编译安装 tar xf pip-1.5.4.tar.gz cd pip-1.5.4 python setup.py install 温馨提示：pip升级命令python setup.py install 3.使用pip安装软件包 pip install sphinx sphinx-autobuild sphinx_rtd_theme
这一步时间会安装很多python依赖，耐心等等.. 只要是成功就可以
初始化
# 创建文档存储目录 mkdir /data1/wiki cd /data1/wiki
当我们使用pip将上面的依赖包安装完毕，就会有sphinx-quickstart命令
初始化完毕后会生成以下的目录结构
三、Web界面优化
sed -i s/alabaster/sphinx_rtd_theme/g source/conf.py 在添加2行 vim source/conf.py import sphinx_rtd_theme html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
修改完成后，我们可以预览以下
现在静态文件全路径是在/data1/wiki/build/html/
现在静态文件是没法直接访问的，我们在安装一个nginx
1.安装nginx
wget http://nginx.org/download/nginx-1.10.3.tar.gz
yum install -y gcc glibc gcc-c++ prce-devel openssl-devel pcre-devel
useradd -s /sbin/nologin www -M
tar xf nginx-1.10.3.tar.gz && cd nginx-1.10.3
./configure --prefix=/usr/local/nginx-1.10.3 --user=www --group=www --with-http_ssl_module --with-http_stub_status_module
make && make install
ln -s /usr/local/nginx-1.10.3 /usr/local/nginx
手动启动
/usr/local/nginx/sbin/nginx
设置开机启动
echo "/usr/local/nginx/sbin/nginx" >>/etc/rc.local
2.配置nginx
[root@i4t.com conf]# grep -Ev "^$|#" /usr/local/nginx/conf/nginx.conf
worker_processes 1;
events {
worker_connections 1024;
}
http {
include mime.types;
default_type application/octet-stream;
sendfile on;
keepalive_timeout 65;
server {
listen 80;
server_name localhost;
location / {
root /data1/wiki/build/html/; ##需要修改的地方！
index index.html index.htm;
}
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root html;
}
}
}
/usr/local/nginx/sbin/nginx -s reload
## 配置nginx只需要修改站点目录即可
效果预览
添加一篇文章，在source目录下新建test.rst，步骤如下:
[root@i4t wiki]# ls build make.bat Makefile source [root@i4t wiki]# mkdir source/test -p [root@i4t wiki]# echo "123" >>source/test/test.rst [root@i4t wiki]# vim source/test/test.rst hello,world abcdocker ======================= #下划线要超过文字，否则会报错 #请按照我的写法进行操作，后面安装markdown插件可以不使用这种写法
index.rst修改如下
.. toctree:: :maxdepth: 2 :caption: Contents: test/test.rst #温馨提示，如果不创建test目录，也可以直接在source下面创建文件
注意中间的空行,需要对其，否则报错。空间为3个空格
效果预览
更换到有Makefile的目录下，执行make html
打开浏览器进行预览
四、markdown语法编写
默认不支持markdown写法，需要安装recommonmark插件
pip install recommonmark
还需要修改conf.py文件
#编辑配置文件source/conf.py在最后一行复制下方配置
from recommonmark.parser import CommonMarkParser
source_parsers = {
'.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']
检查是否含有报错
编写一个md文件进行测试
[root@i4t wiki]# ls build make.bat Makefile source [root@i4t wiki]# cat source/test/i4t.md
index.rst文件配置添加一条i4t.md即可 .. toctree:: :maxdepth: 2 :caption: Contents: test/test.rst test/i4t.md
每次修改文件都需要执行make html
访问查看
五、插入图片说明
默认不支持外键插入图片，我们只能将图片下载下来
例子
把图片放到一个目录里面，直接引用即可。还可以使用相关的markdown工具写完直接导出md文件，然后将图片上传到目录即可
更多功能参考：https://www.xncoding.com/2017/01/22/fullstack/readthedoc.html
相关文章：
- Kubernetes 1.14 二进制集群安装
- Nagios 配置及监控
- 消息队列 Kafka –未完
- Kuerbernetes 1.11 集群二进制安装
