搭建ReadtheDocs Wiki文档 bookstack搭建

摘选:https://i4t.com/3587.html

一、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界面优化

• x主题优化 由于默认主题比较丑，我们替换confi.py文件更换主]

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()]

修改完成后，我们可以预览一下
构建命令make html

现在静态文件全路径是在/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只需要修改站点目录即可

效果预览

• x测试页面编写 接下来我们编写一个测试页面

添加一篇文章，在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