快速开发：用Python快速编写博客平台

10个优秀的程序员里，9个都有写博客的习惯。

这是非常好的习惯，它使得知识得以提炼，转输出为输入，在提升自己的同时，还能利用互联网易传播的特性，将知识分享给每一个热爱学习的人。所以写博客，是值得每个程序员投入时间和精力去坚持做下去的事。

博客既然是自己的一个知识宝库，那么索引将变得极为重要。通过自己的探索，笔者发现了一个能够很好地满足这个需求的 Python 框架 Sphnix。

实现的大体的思路如下：

Markdown：书写文档；

Pandoc：格式转化；

Sphinx：生成网页；

GitHub：托管项目；

ReadtheDocs：发布网页；

接下来，就来看看到底是如何实现的？

安装Sphnix

首先是安装Sphnix。在安装前，请确认下Python版本。本文使用的是Python 2.7.14，其他版本请自行尝试（建议跟笔者一样使用 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脚本；

配置及扩展

Sphinx的配置文件是sourceconifg.py。

由于修改的内容多且杂，为了使搭建过程更加顺畅，需要进行Sphinx配置，包括配置主题、支持LaTeX以及支持中文检索等等。

配置文件还需要搭配相应的扩展模块才能使用，有时候还会用到一些第三方依赖包：

greenlet==0.4.5

oauthlib==0.7.2

paho-mqtt==1.0

tzlocal==1.1.2

redis==2.10.3

requests==2.4.3

requests-oauthlib==0.4.2

whitenoise==1.0.3

openpyxl==2.1.5

撰写文章

万事俱备，接下来就要写文档了。

在source目录下，新增文件how_to_be_a_rich_man.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

点击我们刚写的暴富指南：

托管项目

看到网页的那一刻是不是相当激动？不过别激动，这只是本地的，我们需要将其发布在线上。

这里笔者将工程文件托管在了GitHub上，然后由Read the Docs发布。

在托管之前还需要些准备工作。在mkdocs根目录下，添加文件.gitignore（聪明的你，肯定知道这是什么），内容如下：

build/

.idea/

*.pyc

接下来，在你的GitHub上新建一个仓库。然后把mkdocs目录下的所有文件都提交上去。步骤很简单，这里就不再赘述。

发布上线

托管完成后，我们要发布它让别人访问。

你需要先去Read the Docs注册帐号。然后关联GitHub：

导入代码库，填好与你对应的信息：

构建网页后，右下方可以看见你的在线地址：

这里要提醒的是，Sphinx文档默认是rst格式，如果你习惯了使用Markdown来写文章，可以使用Pandoc这个神器转换一下。

这里给出转换命令：

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

或者你也可以在Sphinx上添加支持Markdown渲染的扩展模块及配置，也很简单。但是，使用md文件在网站上的导航无法实现跳转。

到这里，属于你的个人博客就搭建好了。

成品展示

以笔者的博客（mings-blog.rtfd.io）为例，给大家展示一下最终效果。

这是首页，显示了所有的文章索引。

这是导航栏，结构很清晰，也很方便索引。

点击文章后，还可以很方便地查看标题和跳转。

体验下搜索功能，速度很快。

看完这些你是不是也很想拥有这样一个博客呢？快试一下吧。