使用 Python 30分钟 教你快速搭建一个博客

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

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

实现的大体的思路如下:

Markdown:书写文档
Pandoc:格式转化
Sphinx:生成网页
GitHub:托管项目
ReadtheDocs:发布网页

接下来,就来看看到底是如何实现的?

成品展示

以我的博客为例,先给大家展示一下。

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

使用 Python 30分钟 教你快速搭建一个博客

这是我的导航栏。是不是结构很清晰,很方便索引。

使用 Python 30分钟 教你快速搭建一个博客

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

使用 Python 30分钟 教你快速搭建一个博客

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

使用 Python 30分钟 教你快速搭建一个博客

看完这些你是不是也很想拥有这样一个博客呢?

只要你认真往下看,30分钟搭建这样一个博客不在话下。

安装Sphnix

安装之前,请确认下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脚本。你也不用管。

配置及扩展

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

由于修改的内容比较多而杂,为了使这个搭建过程,更加顺畅。

小明已经给你精心准备了一份配置文件。你只要关注我的公众号,后台直接回复「Sphinx」即可获取。

关于配置文件,我做了哪些事:

配置主题
支持LaTeX
支持中文检索

以上配置文件,需要搭配扩展模块才能使用。扩展模块同样我也给你准备好了,在你回复「Sphinx」后,获取压缩包后,里面有个 exts 文件夹。你只要将这个文件夹原封不动的放置在与source的同级目录下即可。

由于扩展模块会用到一些第三方依赖包,需要你去包装它。requirements.txt 同样我也给你准备好了,在压缩包里有。

你只要执行这个命令,即可安装。

pip install -r requirements.txt -i https://pypi.douban.com/simple/
撰写文章

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

在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

使用 Python 30分钟 教你快速搭建一个博客

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

使用 Python 30分钟 教你快速搭建一个博客

托管项目

看到网页的那一刻是不是相当激动。

不过别激动,这只是本地的,我们需要将其发布在线上。

这里我将工程文件,托管在GitHub上,然后由Read the Docs发布。

在托管之前呢,我们需要准备工作。在mkdocs根目录下,添加文件.gitignore(聪明的你,肯定知道这是什么),内容如下


build/
.idea/
*.pyc

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

发布上线

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

你需要先去 Read the Docs 注册下帐号。

关联一下GitHub

使用 Python 30分钟 教你快速搭建一个博客

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

使用 Python 30分钟 教你快速搭建一个博客

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

使用 Python 30分钟 教你快速搭建一个博客

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

这里给出转换命令。

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

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

到这里,属于你的个人博客就搭建好了,快去试一下吧。


原文发布时间为:2018-08-11

本文作者:Python编程时光

本文来自云栖社区合作伙伴“Python中文社区”,了解相关信息可以关注“Python中文社区”。

上一篇:Python测算女朋友还完花呗多久后吃土


下一篇:《邪不压正》到底怎么样?我爬取了上万条网友评论进行分析