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