使用ReadtheDocs搭建属于自己的博客

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

这里先放两张效果图,各位看官在看是否要搭建

image_1d5bqio601nc51nn1h8ja42agk93.png-138kB

image_1d5bqjc59ogsini1gb717qe1v5o9g.png-375.8kB

二、环境安装

环境说明

环境不一致可能会导致导入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依赖,耐心等等.. 只要是成功就可以

image_1d5bkmgla15mb100jot5m4g12a91b.png-361.2kB

初始化

# 创建文档存储目录
mkdir /data1/wiki
cd /data1/wiki

当我们使用pip将上面的依赖包安装完毕,就会有sphinx-quickstart命令

image_1d5bkvukj17guji8vjg2d9vr71o.png-342.1kB

image_1d5bl1ipaglm188b13c211h9i7q25.png-426.6kB

初始化完毕后会生成以下的目录结构

image_1d5ble14g12i35jd15mv6ja1hbr2i.png-47.9kB

三、Web界面优化

  • 主题优化 由于默认主题比较丑,我们替换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()]

修改完成后,我们可以预览以下

333333.png-203.9kB

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

效果预览

image_1d5bn3m6m1gt517np1o9ubme1bjr3k.png-114.5kB

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

添加一篇文章,在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插件可以不使用这种写法

image_1d5bnbudjhs31sln1bls1fsdkom41.png-60.6kB

index.rst修改如下

.. toctree::
   :maxdepth: 2
   :caption: Contents:


   test/test.rst    #温馨提示,如果不创建test目录,也可以直接在source下面创建文件

注意中间的空行,需要对其,否则报错。空间为3个空格

效果预览

更换到有Makefile的目录下,执行make html

444.png-295.9kB

打开浏览器进行预览

555.png-201.3kB

四、markdown语法编写

默认不支持markdown写法,需要安装recommonmark插件

pip install recommonmark

还需要修改conf.py文件

#编辑配置文件source/conf.py在最后一行复制下方配置
from recommonmark.parser import CommonMarkParser
source_parsers = {
    '.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']

检查是否含有报错

image_1d5bo8e08ge4bcpvumvjvdts60.png-177.5kB

编写一个md文件进行测试

[root@i4t wiki]# ls
build  make.bat  Makefile  source
[root@i4t wiki]# cat source/test/i4t.md

image_1d5bp3k4812ri14fc1a1jo0f13lo72.png-66.5kB

index.rst文件配置添加一条i4t.md即可
.. toctree::
   :maxdepth: 2
   :caption: Contents:

   test/test.rst
   test/i4t.md

313131.png-191.4kB

每次修改文件都需要执行make html

image_1d5bp7lbvdoepmdddrl0ls37f.png-238kB

访问查看

image_1d5bp8v2i1vra9uot8k5vslju7s.png-135.9kB

五、插入图片说明

默认不支持外键插入图片,我们只能将图片下载下来

例子

image_1d5bpdh8d16vv97h1s3ot161l7989.png-155.3kB

把图片放到一个目录里面,直接引用即可。还可以使用相关的markdown工具写完直接导出md文件,然后将图片上传到目录即可

image_1d5bpfhp5b6t1qt8117lo0r1khd8m.png-310.5kB

更多功能参考:https://www.xncoding.com/2017/01/22/fullstack/readthedoc.html

「点点赞赏,手留余香」

    还没有人赞赏,快来当第一个赞赏的人吧!
2 条回复 A 作者 M 管理员
  1. 可以使用!
    • 持续关注!
欢迎您,新朋友,感谢参与互动!欢迎您 {{author}},您在本站有{{commentsCount}}条评论