成品展示

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

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 文件，在网站上的导航无法实现跳转。

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

标签：

版权申明：本站文章部分自网络，如有侵权，请联系：west999com@outlook.com
特别注意：本站所有转载文章言论不代表本站观点，本站所提供的摄影照片，插画，设计作品，如需使用，请与原作者联系，版权归原作者所有