Python利用sphinx構建個人博客「文末含shell筆記」
阿新 • • 發佈:2018-10-31
開發語言 實現 就是 特殊 系統 自動 iar 版本控制系統 template 一、基礎概念
利用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筆記」