利用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

[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

• 導入代碼庫
  

• 項目編譯
  
• 可以通過連接地址查看博客
  

四、查看

鏈接地址：

日常博客

myshell-note

Python利用sphinx構建個人博客「文末含shell筆記」