成品展示

這是我的導航欄。是不是結構很清晰，很方便索引。

Python很容易學！小編有弄一個交流，互問互答，資源共享的交流學習基地，如果你也是Python的學習者或者大牛都歡迎你來！?：548+377+875！一起 學習共同進步！源碼進群獲取！所有都是免費的！不用擔心付費哦！~

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

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

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

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

02

安裝Sphinx

安裝之前，請確認下Python版本。我這裏使用的是Python 2.7.14，其他版本請自行嘗試（Py3有點不一樣，不想踩坑的，請跟我一樣使用 Py2）。

安裝Python工具包

$ pip install sphinx sphinx-autobuild sphinx_rtd_theme

初始化

# 先創建一個工程目錄: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：bat腳本。你也不用管。

03

配置及擴展

Sphinx 的配置文件是 sourceconifg.py

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

小明已經給你精心準備了一份配置文件。你只要關註我的公眾號，後臺直接回復 「Sphinx」即可獲取。

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

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

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

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

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

pip install -r requirements.txt -i https://pypi.douban.com/simple/

04

撰寫文章

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

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

文件內容如下

第一章 如何成為有錢人

======================

1.1 財富繼承法

---------------------

有個有錢的老爸。

1.2 財富共享法

---------------------

有個有錢的老婆。

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

排版配置文件是 sourceindex.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 buildhtml.

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

我們點進去 buildhtml，打開index.html

點擊 我們剛寫的暴富指南。

05

托管項目

看到網頁的那一刻是不是相當激動。

不過別激動，這只是本地的，我們需要將其發布在線上。

這裏我將工程文件，托管在GitHub上，然後由Read the Docs發布。

在托管之前呢，我們需要準備工作。在mkdocs根目錄下，添加文件.gitignore（聰明的你，肯定知道這是什麽），內容如下

build/

.idea/

*.pyc

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

06

發布上線

托管完成後，我們要發布它，讓別人可以訪問。

你需要先去 Read the Docs 註冊下帳號。

關聯一下GitHub

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

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

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

這裏給出轉換命令。

pandoc -V mainfont="SimSun" -f markdown -t rst hello.md -o hello.rst

或者你也可以在Sphinx上添加支持Markdown渲染的擴展模塊及配置。也很簡單，但是，我發現使用 md 文件，在網站上的導航無法實現跳轉。

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

博客是一個程序員的門面！它的博客覺得他的薪資！十分鐘搭建一個