使用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. 1.下载pip源码包
  2. wget "https://pypi.python.org/packages/source/p/pip/pip-1.5.4.tar.gz#md5=834b2904f92d46aaa333267fb1c922bb" --no-check-certificate
  3. 2.编译安装
  4. tar xf pip-1.5.4.tar.gz
  5. cd pip-1.5.4
  6. python setup.py install
  7. 温馨提示:pip升级命令python setup.py install
  8. 3.使用pip安装软件包
  9. pip install sphinx sphinx-autobuild sphinx_rtd_theme

这一步时间会安装很多python依赖,耐心等等.. 只要是成功就可以
image_1d5bkmgla15mb100jot5m4g12a91b.png-361.2kB

初始化

  1. # 创建文档存储目录
  2. mkdir /data1/wiki
  3. cd /data1/wiki

当我们使用pip将上面的依赖包安装完毕,就会有sphinx-quickstart命令
image_1d5bkvukj17guji8vjg2d9vr71o.png-342.1kB
image_1d5bl1ipaglm188b13c211h9i7q25.png-426.6kB

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

image_1d5ble14g12i35jd15mv6ja1hbr2i.png-47.9kB

三、Web界面优化

  • 主题优化 由于默认主题比较丑,我们替换confi.py文件更换主]
  1. sed -i s/alabaster/sphinx_rtd_theme/g source/conf.py
  2. 在添加2
  3. vim source/conf.py
  4. import sphinx_rtd_theme
  5. html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

修改完成后,我们可以预览以下
333333.png-203.9kB

现在静态文件全路径是在/data1/wiki/build/html/

现在静态文件是没法直接访问的,我们在安装一个nginx

  1. 1.安装nginx
  2. wget http://nginx.org/download/nginx-1.10.3.tar.gz
  3. yum install -y gcc glibc gcc-c++ prce-devel openssl-devel pcre-devel
  4. useradd -s /sbin/nologin www -M
  5. tar xf nginx-1.10.3.tar.gz && cd nginx-1.10.3
  6. ./configure --prefix=/usr/local/nginx-1.10.3 --user=www --group=www --with-http_ssl_module --with-http_stub_status_module
  7. make && make install
  8. ln -s /usr/local/nginx-1.10.3 /usr/local/nginx
  9. 手动启动
  10. /usr/local/nginx/sbin/nginx
  11. 设置开机启动
  12. echo "/usr/local/nginx/sbin/nginx" >>/etc/rc.local
  13. 2.配置nginx
  14. [root@i4t.com conf]# grep -Ev "^$|#" /usr/local/nginx/conf/nginx.conf
  15. worker_processes 1;
  16. events {
  17. worker_connections 1024;
  18. }
  19. http {
  20. include mime.types;
  21. default_type application/octet-stream;
  22. sendfile on;
  23. keepalive_timeout 65;
  24. server {
  25. listen 80;
  26. server_name localhost;
  27. location / {
  28. root /data1/wiki/build/html/; ##需要修改的地方!
  29. index index.html index.htm;
  30. }
  31. error_page 500 502 503 504 /50x.html;
  32. location = /50x.html {
  33. root html;
  34. }
  35. }
  36. }
  37. /usr/local/nginx/sbin/nginx -s reload
  38. ## 配置nginx只需要修改站点目录即可

效果预览
image_1d5bn3m6m1gt517np1o9ubme1bjr3k.png-114.5kB

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

添加一篇文章,在source目录下新建test.rst,步骤如下:

  1. [root@i4t wiki]# ls
  2. build make.bat Makefile source
  3. [root@i4t wiki]# mkdir source/test -p
  4. [root@i4t wiki]# echo "123" >>source/test/test.rst
  5. [root@i4t wiki]# vim source/test/test.rst
  6. hello,world abcdocker
  7. =======================
  8. #下划线要超过文字,否则会报错
  9. #请按照我的写法进行操作,后面安装markdown插件可以不使用这种写法

image_1d5bnbudjhs31sln1bls1fsdkom41.png-60.6kB

index.rst修改如下

  1. .. toctree::
  2. :maxdepth: 2
  3. :caption: Contents:
  4. test/test.rst #温馨提示,如果不创建test目录,也可以直接在source下面创建文件

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

效果预览
更换到有Makefile的目录下,执行make html
444.png-295.9kB

打开浏览器进行预览
555.png-201.3kB

四、markdown语法编写

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

  1. pip install recommonmark

还需要修改conf.py文件

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

检查是否含有报错
image_1d5bo8e08ge4bcpvumvjvdts60.png-177.5kB

编写一个md文件进行测试

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

image_1d5bp3k4812ri14fc1a1jo0f13lo72.png-66.5kB

  1. index.rst文件配置添加一条i4t.md即可
  2. .. toctree::
  3. :maxdepth: 2
  4. :caption: Contents:
  5. test/test.rst
  6. 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


    A+
发布日期:2019年03月07日  所属分类:Linux
标签:
新闻联播老司机

发表评论

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

目前评论:2   其中:访客  2   博主  0

  1. 98k 3
    可以使用!
    • 新闻联播老司机 新闻联播老司机 2
      持续关注!