一、基礎概念

利用sphinx+pandoc+github+readthedocs構建個人部落格

• Sphinx： 是一個基於ReStructuredText的文件生成工具，可以令人輕鬆的撰寫出清晰且優美的文件, 由Georg Brandl在BSD許可證下開發。新版的Python文件就是由Sphinx生成的，並且它已成為Python專案首選的文件工具，同時它對C/C++專案也有很好的支援；並計劃對其它開發語言新增特殊支援。
• Read the Docs是一個線上文件託管服務，可以從各種版本控制系統中匯入文件。支援webhooks，當你提交程式碼時，文件將被自動構建。
• Pandoc
  ：pandoc是一款開源轉換工具，可以實現常見的格式轉換。支援全平臺操作，以命令列的方式進行轉換。

二、流程

Sphinx + GitHub + ReadtheDocs 作為一個文件寫作工具，利用pandoc文字轉換， 用Sphinx生成文件，GitHub託管文件，再匯入到 ReadtheDocs。我們可以使用這個工具寫文件、記筆記等。

三、實施部署

3.1 安裝環境

此處利用的centos7.4 系統預設python版本2.7

[[email protected] ~]# cat /etc/redhat-release 
CentOS Linux release 7.3.1611 (Core) 
[
 
[email protected] ~]# 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 目錄結構

[[email protected] 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

[[email protected] source]# pandoc -s -t rst --toc myshell-note.md -o myshell-note.rst
[[email protected] 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    # 生成網頁檔案

[[email protected] build]# ls
doctrees  html

3.10 將頁面專案託管至github

如果不會github可以參考git筆記

3.11 關聯github和read the docs

如果沒有readthedocs賬號可以通過github賬號登陸

readthedocs登陸地址

• 管理github

• 匯入程式碼庫
  
• 專案編譯
  
• 可以通過連線地址檢視部落格
  

四、檢視

連結地址：

日常部落格

myshell-note