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

释放双眼,带上耳机,听听看~!
Read the Docs是一个在线文档托管服务, 你可以从各种版本控制系统中导入文档,如果你使用webhooks, 那么每次提交代码后可以自动构建并上传至readthedocs网站,非常方便。
🤖 由 ChatGPT 生成的文章摘要

搭建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

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

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

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

二、环境安装

环境说明

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

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

初始化

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

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

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

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

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

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

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

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

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

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

效果预览

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

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

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

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

index.rst修改如下

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


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

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

效果预览

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

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

打开浏览器进行预览

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

四、markdown语法编写

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

pip install recommonmark

还需要修改conf.py文件

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

检查是否含有报错

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

编写一个md文件进行测试

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

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

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

   test/test.rst
   test/i4t.md

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

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

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

访问查看

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

五、插入图片说明

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

例子

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

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

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

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

给TA打赏
共{{data.count}}人
人已打赏
Linux

Linux性能监控工具 gtop

2018-12-13 17:27:26

Linux

消息队列 Kafka –未完

2019-3-27 15:39:25

2 条回复 A文章作者 M管理员
  1. 可以使用!

个人中心
购物车
优惠劵
今日签到
有新私信 私信列表
搜索