10个优秀的程序员里,9个都有写博客的习惯。
学习Python中有不明白推荐加入交流裙
号:735934841
群里有志同道合的小伙伴,互帮互助,
群里有免费的视频学习教程和PDF!
这是非常好的习惯,它使得知识得以提炼,转输出为输入,在提升自己的同时,还能利用互联网易传播的特性,将知识分享给每一个热爱学习的人。所以写博客,是值得每个程序员投入时间和精力去坚持做下去的事。
博客既然是自己的一个知识宝库,那么索引将变得极为重要。通过自己的探索,笔者发现了一个能够很好地满足这个需求的 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)为例,给大家展示一下最终效果。
这是首页,显示了所有的文章索引。
这是导航栏,结构很清晰,也很方便索引。
点击文章后,还可以很方便地查看标题和跳转。
体验下搜索功能,速度很快。
看完这些你是不是也很想拥有这样一个博客呢?快试一下吧。