0個(gè)優(yōu)秀的程序員里,有9個(gè)人都有寫博客的習(xí)慣。這是非常好的習(xí)慣,它使得知識得以提煉,轉(zhuǎn)輸出為輸入,在提升自己的同時(shí),還能利用互聯(lián)網(wǎng)易
Markdown:書寫文檔
Pandoc:格式轉(zhuǎn)化
Sphinx:生成網(wǎng)頁
GitHub:托管項(xiàng)目
ReadtheDocs:發(fā)布網(wǎng)頁
接下來,就來看看到底是如何實(shí)現(xiàn)的?
01
成品展示
以我的博客為例,先給大家展示一下。這是首頁。顯示了你所有的文章索引。
這是我的導(dǎo)航欄。是不是結(jié)構(gòu)很清晰,很方便索引。
點(diǎn)擊文章后,還可以很方便查看標(biāo)題,跳轉(zhuǎn)。
體驗(yàn)下搜索功能,速度很快。
看完這些你是不是也很想擁有這樣一個(gè)博客呢?只要你認(rèn)真往下看,30分鐘搭建這樣一個(gè)博客不在話下。
02
安裝Sphnix
安裝之前,請確認(rèn)下Python版本。我這里使用的是Python 2.7.14,其他版本請自行嘗試(Py3有點(diǎn)不一樣,不想踩坑的,請跟我一樣使用 Py2)。安裝Python工具包$ pip install sphinx sphinx-autobuild sphinx_rtd_theme
初始化# 先創(chuàng)建一個(gè)工程目錄:F:\\mkdocs
$ cd F:\\mkdocs
$ sphinx-quickstart
執(zhí)行這個(gè)命令sphinx-quickstart的時(shí)候,會讓你輸入配置。除了這幾個(gè)個(gè)性化配置,其他的都可以按照默認(rèn)的來。> Project name: MING's BLOG
> Author name(s): MING
> Project release []: 1.0
> Project language [en]: zh_CN
完了后,就可以看見創(chuàng)建的工程文件。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:文件夾,當(dāng)你執(zhí)行make html的時(shí)候,生成的html靜態(tài)文件都存放在這里。
source:文件夾:你的文檔源文件全部應(yīng)全部放在source根目錄下。
Makefile:編譯文件。完全不用管。
make.bat:bat腳本。你也不用管。
03
配置及擴(kuò)展
Sphinx 的配置文件是 source\conifg.py由于修改的內(nèi)容比較多而雜,為了使這個(gè)搭建過程,更加順暢。小明已經(jīng)給你精心準(zhǔn)備了一份配置文件。你只要關(guān)注我的公眾號,后臺直接回復(fù)「Sphinx」即可獲取。關(guān)于配置文件,我做了哪些事:
配置主題
支持LaTeX
支持中文檢索
以上配置文件,需要搭配擴(kuò)展模塊才能使用。擴(kuò)展模塊同樣我也給你準(zhǔn)備好了,在你回復(fù)「Sphinx」后,獲取壓縮包后,里面有個(gè) exts 文件夾。你只要將這個(gè)文件夾原封不動的放置在與source的同級目錄下即可。由于擴(kuò)展模塊會用到一些第三方依賴包,需要你去包裝它。requirements.txt 同樣我也給你準(zhǔn)備好了,在壓縮包里有。你只要執(zhí)行這個(gè)命令,即可安裝。pip install -r requirements.txt -i www.idiancai.com/simple/
04
撰寫文章
萬事俱備,接下來要寫文檔了。在source目錄下,新增文件 how_to_be_a_rich_man.rst(至于什么是rst格式呢,請自行搜索引擎噢)文件內(nèi)容如下第一章 如何成為有錢人
======================
1.1 財(cái)富繼承法
---------------------
有個(gè)有錢的老爸。
1.2 財(cái)富共享法
---------------------
有個(gè)有錢的老婆。
寫好文檔后,千萬記得要把這個(gè)文檔寫進(jìn),目錄排版里面。排版配置文件是 source\index.rst,千萬要注意中間的空行不可忽略。.. toctree::
:maxdepth: 2
:caption: Contents:
how_to_be_a_rich_man
然后刪除這幾行Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
然后執(zhí)行make html 生成html靜態(tài)文件。F:\mkdocs
(mkdocs) λ make html
Running Sphinx v1.7.4
loading translations [zh_CN]... done
loading pickled environment... done
building [mo]: targets for0 po files that are outof date
building [html]: targets for2 source files that are outof 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 indexin English (code: en) ... done
dumping object inventory... done
build succeeded.
The HTML pages are in build\html.
執(zhí)行完了后,你可以發(fā)現(xiàn)原先的build,不再是空文件夾了。我們點(diǎn)進(jìn)去www.smpeizi.com/ build/html/,打開index.html
點(diǎn)擊 我們剛寫的暴富指南。
05
托管項(xiàng)目
看到網(wǎng)頁的那一刻是不是相當(dāng)激動。不過別激動,這只是本地的,我們需要將其發(fā)布在線上。這里我將工程文件,托管在GitHub上,然后由Read the Docs發(fā)布。在托管之前呢,我們需要準(zhǔn)備工作。在mkdocs根目錄下,添加文件.gitignore(聰明的你,肯定知道這是什么),內(nèi)容如下build/
.idea/
*.pyc
接下來,在你的GitHub上新建一個(gè)倉庫。然后把mkdocs這個(gè)目錄下的所有文件都提交上去。步驟很簡單,這里就不細(xì)講。
06
發(fā)布上線
托管完成后,我們要發(fā)布它,讓別人可以訪問。你需要先去 Read the Docs 注冊下帳號。關(guān)聯(lián)一下GitHub
導(dǎo)入代碼庫。填好與你對應(yīng)的信息。
構(gòu)建網(wǎng)頁后。右下方,你可以看見你的在線地址www.pzzs168.com。
這里要提醒一下的是,Sphinx的文檔格式,默認(rèn)是 rst 格式,如果你習(xí)慣了使用Markdown來寫文章,可以使用 Pandoc 這個(gè)神器轉(zhuǎn)換一下。
這里給出轉(zhuǎn)換命令。
pandoc -V mainfont="SimSun" -f markdown -t rst hello.md -o hello.rst
或者你也可以在Sphinx上添加支持Markdown渲染的擴(kuò)展模塊及配置。也很簡單,但是,我發(fā)現(xiàn)使用 md 文件,在網(wǎng)站上的導(dǎo)航無法實(shí)現(xiàn)跳轉(zhuǎn)。
到這里,屬于你的個(gè)人博客就搭建好了,快去試一下吧。????
Python交流群
635448130點(diǎn)擊加入群聊UI設(shè)計(jì)交流群
579150876點(diǎn)擊加入群聊Unity交流群
495609038點(diǎn)擊加入群聊HTML5交流群
645591648點(diǎn)擊加入群聊