Python利用sphinx构建我的博客

1、基础概念

利用sphinx+pandoc+github+readthedocs构建我的博客

• Sphinx： 是一个基于ReStructuredText的文档生成工具，能够使人轻松的撰写出清晰且优美的文档, 由Georg Brandl在BSD许可证下开发。新版的Python文档就是由Sphinx生成的，而且它已成为Python项目首选的文档工具，同时它对C/C++项目也有很好的支持；并计划对其它开发语言添加特殊支持。
• Read the Docs是一个在线文档托管服务，能够从各类版本控制系统中导入文档。支持webhooks，当你提交代码时，文档将被自动构建。
• ** Pandoc**：pandoc是一款开源转换工具，能够实现常见的格式转换。支持全平台操做，以命令行的方式进行转换。

2、流程

Sphinx + GitHub + ReadtheDocs 做为一个文档写做工具，利用pandoc文本转换， 用Sphinx生成文档，GitHub托管文档，再导入到 ReadtheDocs。咱们可使用这个工具写文档、记笔记等。

3、实施部署

3.1 安装环境

此处利用的centos7.4 系统默认python版本2.7

[root@xuel-server ~]# cat /etc/redhat-release 
CentOS Linux release 7.3.1611 (Core) 
[root@xuel-server ~]# python --version
Python 2.7.5
须要安装git
复制代码

3.2 pip 安装sphinx环境

pip install sphinx sphinx-autobuild sphinx_rtd_theme
复制代码

3.3 初始化项目

mkdir /mywike && cd /mywiki
sphinx-quickstart                 # 执行初始化，如下为本身输入，其余可按照默认直接回车
> Separate source and build directories (y/n) [n]: y    # 建立source目录
> Project name: KaliArch SHELL BLOG         # 项目名称
> Author name(s): KaliArch                  # 做者名称
> Project release []: 1.0                   
复制代码

3.4 目录结构

[root@xuel-server mywike]# tree 
.
├── build           #文件夹，当你执行make html的时候，生成的html静态文件都存放在这里
├── make.bat
├── Makefile        #编译文件用 make 命令时，可使用这些指令来构建文档输出
└── source          #文件夹，文档源文件所有应所有放在source根目录下
    ├── conf.py     #Sphinx 的配置文件
    ├── index.rst
    ├── _static
    └── _templates
复制代码

3.5 修改配置文件

开启sys和os模块

* 配置主题
html_theme = 'alabaster'
* 支持LaTeX
* 支持中文检索
extensions = ['chinese_search']

source_suffix = ['.rst', '.md']
复制代码

因为修改模板较麻烦能够直接git clone个人模板进行简单修改便可

博客git地址

3.6 安装第三方模块

yum install python-devel  
pip install -r requirements.txt -i https://pypi.douban.com/simple/
复制代码

若是报错可能因为下载超时，从新执行便可。

3.7 利用pandoc安装

pandoc下载地址

cd /usr/local
wget -c https://github.com/jgm/pandoc/releases/download/2.2.3.2/pandoc-2.2.3.2-linux.tar.gz
ln -sv pandoc-2.2.3.2 pandoc
echo "export PATH=\$PATH:/usr/local/pandoc/bin" >/etc/profile.d/pandoc.sh
source /etc/profile.d/pandoc.sh
复制代码

3.8 利用pandoc转换文件

利用pandoc将以前的markdown格式的博客源文件转换成rst格式

pandoc -s -t rst --toc markdown.md -o index.rst
复制代码

[root@xuel-server source]# pandoc -s -t rst --toc myshell-note.md -o myshell-note.rst
[root@xuel-server source]# ls
conf.py  index.rst  myshell-note.md  myshell-note.rst  _static  _templates
复制代码

编辑index.rst,进行引用文件

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

   myshell-note
复制代码

3.9 编译生成html文件

cd /mywiki
make html    # 生成网页文件

[root@xuel-server build]# ls
doctrees  html
复制代码

3.10 将页面项目托管至github

若是不会github能够参考git笔记

3.11 关联github和read the docs

若是没有readthedocs帐号能够经过github帐号登录

readthedocs登录地址

• 管理github

• 导入代码库

  

• 项目编译

  

• 能够经过链接地址查看博客

  

4、查看

连接地址：

平常博客

myshell-note