首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >使用 Python 30分钟 教你快速搭建一个博客

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

作者头像
小小詹同学
发布2019-11-12 17:26:04
9600
发布2019-11-12 17:26:04
举报
文章被收录于专栏:小詹同学小詹同学

本文来源:python编程时光,欢迎大家关注

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

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

实现的大体的思路如下:

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

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

01 成品展示


以我的博客(mings-blog.rtfd.io)为例,先给大家展示一下。

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

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

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

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

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

只要你认真往下看,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 的配置文件是 source\conifg.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 财富共享法 --------------------- 有个有钱的老婆。

写好文档后,千万记得要把这个文档写进,目录排版里面。

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

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

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

本文参与 腾讯云自媒体分享计划,分享自微信公众号。
原始发表:2018-09-07,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 小詹学Python 微信公众号,前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体分享计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 01 成品展示
  • 02 安装Sphinx
  • 03 配置及扩展
  • 04 撰写文章
  • 05 托管项目
  • 06 发布上线
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档