30分鐘教你使用Python搭建一個博客

10個優秀的程序員裏，有9我的都有寫博客的習慣。記錄總結，就是一個輸出的過程，值得每一個程序員，投入時間和精力去堅持作下去。

寫博客的平臺有不少，CSDN，博客園等，除此以外，還會有不少人會使用Hexo，WordPress，比較會折騰的人還會本身使用Java，Python搭建，我就幹過這樣的事，不過每一年還要支付域名和服務器，比較麻煩並且費錢。

以上博客平臺我都有註冊使用過，不過最終仍是放棄。由於他們的博客文章，相對比較零散，沒法造成一個系統性的知識體系，不便索引（我的感受，也多是我使用問題）。

爲了使本身的文章能有一個比較完整的體系。通過一番探索以後，能知足個人基本要求的有以下兩種：

• GitHub Wiki，適合作知識整理，但排版通常，不方便查看。
• GitBook，樣式很差看，訪問速度慢。

因爲以上兩種都有各自的不足的地方，因此我最後選擇了一個完美的解決方案：Markdown+Pandoc+Sphinx+GitHub+ReadtheDocs 來管理個人文章。

• Markdown：書寫文檔
• Pandoc：格式轉化
• Sphinx：生成網頁
• GitHub：託管項目
• ReadtheDocs：發佈網頁

1. 成品展現

以個人博客(python-online.cn)爲例，先給你們展現一下。

這是首頁。顯示了你全部的文章索引。

這是個人導航欄。是否是結構很清晰，很方便索引。

點擊文章後，還能夠很方便查看標題，跳轉。

體驗下搜索功能，速度很快。

看完這些你是否是也很想擁有這樣一個博客呢？

只要你認真往下看，30分鐘搭建這樣一個博客不在話下。

2. 安裝Sphinx

安裝以前，請確認下Python版本。我這裏使用的是Python 2.7.14，其餘版本請自行嘗試噢，Python3.6好像有些坑，你須要踩一下。

安裝Python工具包

$ pip install sphinx sphinx-autobuild sphinx_rtd_theme -i https://pypi.douban.com/simple/
複製代碼

初始化

# 先建立一個工程目錄:F:\mkdocs
$ cd F:\mkdocs

$ sphinx-quickstart
複製代碼

執行這個命令sphinx-quickstart的時候，會讓你輸入配置。除了這幾個個性化配置，其餘的均可以按照默認的來。

> Project name: MING's BLOG > Author name(s): MING > Project release []: 1.0 > Project language [en]: zh_CN 複製代碼

完了後，就能夠看見建立的工程文件。

F:\mkdocs
(mkdocs) λ ls -l
total 5
-rw-r--r-- 1 wangbm 1049089 610 Jun 23 16:57 Makefile
drwxr-xr-x 1 wangbm 1049089   0 Jun 23 16:57 build/
-rw-r--r-- 1 wangbm 1049089 817 Jun 23 16:57 make.bat
drwxr-xr-x 1 wangbm 1049089   0 Jun 23 16:57 source/

F:\mkdocs
(mkdocs) λ tree
卷 文檔 的文件夾 PATH 列表
卷序列號爲 0002-B4B9
F:.
├─build
└─source
    ├─_static
    └─_templates
複製代碼

解釋下這些文件/夾：

• build：文件夾，當你執行make html的時候，生成的html靜態文件都存放在這裏。
• source：文件夾：你的文檔源文件所有應所有放在source根目錄下。
• Makefile：不用管。
• make.bat：也不用管。

3. 配置及擴展

Sphinx 的配置文件是 source\conifg.py

因爲修改的內容比較多而雜，爲了使這個搭建過程，更加順暢。

小明已經給你精心準備了一份配置文件。你只要關注個人公衆號「Python編程時光」，後臺直接回復 「Sphinx」便可獲取。

關於配置文件，我作了哪些事：

• 配置主題
• 支持LaTeX
• 支持中文檢索

以上配置文件，須要搭配擴展模塊才能使用。擴展模塊一樣我也給你準備好了，在你回覆「Sphinx」後，獲取壓縮包後，裏面有個 exts 文件夾。你只要將這個文件夾原封不動的放置在與source的同級目錄下便可。

因爲擴展模塊會用到一些第三方依賴包，須要你去包裝它。requirements.txt 一樣我也給你準備好了，在壓縮包裏有。

你只要執行這個命令，便可安裝。

pip install -r requirements.txt -i https://pypi.douban.com/simple/
複製代碼

4. 撰寫文章

萬事俱備，接下來要寫文檔了。

在source目錄下，新增文件 how_to_be_a_rich_man.rst（至於什麼是rst格式呢，請自行搜索引擎噢）

文件內容以下

第一章 如何成爲有錢人
======================

1.1 財富繼承法
---------------------

有個有錢的老爸。


1.2 財富共享法
---------------------

有個有錢的老婆。
複製代碼

寫好文檔後，千萬記得要把這個文檔寫進，目錄排版裏面。

排版配置文件是 source\index.rst，千萬要注意中間的空行不可忽略。

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

   how_to_be_a_rich_man
複製代碼

而後刪除這幾行吧，沒啥用。

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
複製代碼

而後執行make html 生成html靜態文件。

F:\mkdocs
(mkdocs) λ make html
Running Sphinx v1.7.4
loading translations [zh_CN]... done
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 2 source files that are out of date
updating environment: [extensions changed] 2 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.

The HTML pages are in build\html.
複製代碼

執行完了後，你能夠發現原先的build，再也不是空文件夾了。

咱們點進去 build\html\ 目錄，使用瀏覽器打開index.html文件。

真棒，已經完成了一半了。點擊 咱們剛寫的 暴富指南。

5. 託管項目

看到網頁的那一刻是否是至關激動。

不過別激動，這只是本地的，咱們須要將其發佈在線上。

這裏我將工程文件，託管在GitHub上，而後由Read the Docs發佈。

在託管以前呢，咱們須要準備工做。在mkdocs根目錄下，添加文件.gitignore（聰明的你，確定知道這是什麼），內容以下

build/
.idea/
*.pyc
複製代碼

接下來，在你的GitHub上新建一個倉庫。而後把mkdocs這個目錄下的全部文件都提交上去。步驟很簡單，這裏就不細講了。

4.3.6 發佈上線

託管完成後，咱們要發佈它，讓別人也可使用公網訪問。

你須要先去 Read the Docs 註冊下賬號。

關聯一下GitHub

導入代碼庫。填好與你對應的信息。

構建網頁後。右下方，你能夠看見你的在線地址。

這裏要提醒一下的是，Sphinx的文檔格式，默認是 rst 格式，若是你習慣了使用Markdown來寫文章，可使用 Pandoc 這個神器轉換一下。

這裏給出格式轉換命令。

pandoc -V mainfont="SimSun" -f markdown -t rst hello.md -o hello.rst
複製代碼

到這裏，屬於你的我的博客就搭建好了，快去試一下吧。

最後，整個項目的源碼和模塊包我都放在公衆號（Python編程時光）後臺，若是你須要的話能夠回覆「Sphinx」領取。另外若是有任何搭建問題歡迎加我微信與我交流。

附錄：參考文檔

• Sphinx配置MarkDown解析
• Sphinx使用手冊(部分漢化)
• 搭建參考文章

---