來(lái)源：Python 技術(shù)「ID: pythonall」

文檔的重要性無(wú)容置疑,，而且文檔編寫(xiě)能力是程序員最重要的軟實(shí)力之一,。不過(guò)編寫(xiě)文檔不僅枯燥，而且后期制作難度高,，誰(shuí)都不愿意做,。

今天我們來(lái)聊一聊，如何利用 markdown[1] 高效地編寫(xiě)閱讀方便結(jié)構(gòu)完整,，甚至支持關(guān)鍵字搜索的 Web 文檔吧,，讓寫(xiě)文檔上癮。開(kāi)干,！

文檔框架

同博客框架 WordPress[2],、Hexo[3] 等一樣，Web 文檔也有自己的框架,，如比如 Java 的 Javadoc[4],，Python 的 pydoc[5]，以及Python-sphinx[6]

對(duì)于 Python 有專(zhuān)門(mén)文檔標(biāo)記語(yǔ)言 reStructuredText（RST）[7],，常見(jiàn)的 Python 各種庫(kù)和工具的幫助文檔基本都是用 RST 所寫(xiě),。

如 Requests[8]、Flask[9],、Scrapy[10] 等,。

例如 Scrapy 的文檔

不過(guò)，用 RST 編寫(xiě)對(duì)于已經(jīng)會(huì)了 Markdown（更為流行） 的讀者來(lái)說(shuō),，有點(diǎn)浪費(fèi),，而且兩者的語(yǔ)法差異較大，容易造成記憶沖突,。

幸運(yùn)的是有了 mkdocs[11],，不僅能輕松制作類(lèi)似 Scrapy 幫助文檔的文檔項(xiàng)目，而且支持 markdown 語(yǔ)法,。

Mkdocs

MkDocs 是一個(gè)快速,、簡(jiǎn)單、可以效果驚艷的采用 Markdown 語(yǔ)法編寫(xiě)的靜態(tài)站點(diǎn)生成器,，主要用于構(gòu)建項(xiàng)目文檔,。

環(huán)境搭建

安裝了 Python，有了 pip,，運(yùn)行以下命令就可以安裝 MkDocs 了：

查看 MkDocs 版本：

如上,，即 MkDocs 安裝正常了。

創(chuàng)建項(xiàng)目

就可以用 MkDocs 創(chuàng)建一個(gè)文檔項(xiàng)目了,。

命令行進(jìn)入需要?jiǎng)?chuàng)建文檔項(xiàng)目的目錄,，然后執(zhí)行：

這樣就在當(dāng)前目錄下,，生成了一個(gè) testdocs 文件夾，就是創(chuàng)建的文檔項(xiàng)目,。

項(xiàng)目目錄結(jié)構(gòu)如下：

mkdocs.yml 為配置文件

docs 文件夾中為文檔文件目錄,，文件使用 markdown 編寫(xiě)。

文檔預(yù)覽

進(jìn)入 testdocs 目錄（也就是創(chuàng)建的文檔項(xiàng)目目錄,，你的可能不同）,，執(zhí)行 mkdocs serve：

將啟動(dòng)一個(gè) Web 服務(wù)器，用于預(yù)覽 testdocs 文件項(xiàng)目,，效果如下：

很驚艷吧,，而且支持多種站點(diǎn)風(fēng)格。

文檔預(yù)覽會(huì)在文檔發(fā)生變化時(shí)自動(dòng)刷新,，可以隨時(shí)看到最新效果,。

編寫(xiě)文檔

搭建好了項(xiàng)目，就可以開(kāi)始編寫(xiě)文檔了,，總體和寫(xiě)這篇文章差不多,。

配置

mkdocs 的配置簡(jiǎn)單明了，采用 yml 格式：

需要注意的是 nav 配置,，當(dāng)文檔比較復(fù)雜時(shí),，可以通過(guò)嵌套的方式。

例如在 Home 下還有子菜單,，menu1 和 menu2,，可以配置成：

效果如下：

• 如果菜單名中有空格需要用引號(hào)(單雙皆可)括起來(lái)
• 文檔文件不要同導(dǎo)航結(jié)構(gòu)配合，可以為導(dǎo)航配置相對(duì)文件路徑
• 菜單層級(jí)可以無(wú)限嵌套

一些約定

文檔編寫(xiě)過(guò)程和寫(xiě)一般的 markdown 文章差不多,，有一些需要注意的地方或是技巧需要說(shuō)明一下,。

1. 站點(diǎn)布局 默認(rèn)情況下，即在不配置導(dǎo)航 (nav) 的情況下,，會(huì)按照文件名,，目錄結(jié)構(gòu)生成導(dǎo)航菜單

2. 站點(diǎn)首頁(yè) 默認(rèn)情況下，必須創(chuàng)建一個(gè) index.md 作為站點(diǎn)首頁(yè),。同時(shí)也支持 README.md 作為首頁(yè),，會(huì)將其轉(zhuǎn)化為 index.html。如果 index.md 和 README.md 同時(shí)存在,，將忽略 README.md

3. 非 markdown 文件 markdown 文件，即擴(kuò)展名為 md 的文件,，會(huì)被轉(zhuǎn)化為 html,。非 markdown 文件，會(huì)被原封拷貝,，不做任何修改

4. 內(nèi)部鏈接 如果需要引用另一個(gè)文件,，只需要按照 markdown 鏈接的方式,，連接到這個(gè)文件就可以了，例如 [詳情請(qǐng)參考](./detail.md),。不要擔(dān)心文件名,，因?yàn)樯烧军c(diǎn)時(shí)會(huì)自動(dòng)換成 html 文件路徑

生成站點(diǎn)

編寫(xiě)好文檔后，需要將其生成為站點(diǎn)目錄,，即編譯成 html 文件,，才能發(fā)布。

使用 mkdocs 非常方便,，只需要在項(xiàng)目目錄中,，執(zhí)行以下命令即可:

完成后，就會(huì)生成一個(gè) site 文件夾,，其中就是生成好的站點(diǎn)文件

發(fā)布

寫(xiě)好文檔,，需要發(fā)布才能讓更多的人看到和使用。

這里介紹兩種發(fā)布方式,，可以根據(jù)實(shí)際情況選擇,。

自主發(fā)布

上一節(jié)，說(shuō)明了如何生成站點(diǎn),，那么只要將生成好的站點(diǎn)文件,，部署到服務(wù)器上就可以。

然后配置 Web 服務(wù)器的虛擬目錄,，例如常用的 nginx

這樣就可以通過(guò) www.yourhost.com/docs 訪問(wèn)到文件了（假如你已經(jīng)有了域名 yourhost.com 并解析到了服務(wù)器上）,。

如果是在公司內(nèi)部的話，只要將站點(diǎn)文件夾拷貝到網(wǎng)絡(luò)網(wǎng)絡(luò)管理員指定的位置,，就可以了,。

自主發(fā)布需要更多的資源和知識(shí)，不過(guò)更自由和保密

Read the Docs

如果自主發(fā)布比較麻煩,，可以選擇 Read the Docs[12],。

它是一個(gè)專(zhuān)門(mén)為文檔而生的 Web 服務(wù)，可以便捷地發(fā)布文檔,，只需要注冊(cè)一個(gè)賬號(hào),。

Read the Docs 提供公開(kāi)和商業(yè)兩種版本，商業(yè)版可以發(fā)布私有文檔,，否則只能發(fā)布公開(kāi)的文檔,，可以根據(jù)實(shí)際情況做出選擇。

Read the Docs 支持 mkdocs 創(chuàng)建的文檔項(xiàng)目,，即,，意味著不需要對(duì) mkdocs 項(xiàng)目進(jìn)行生成站點(diǎn)操作，就可以發(fā)布，這樣就方便多了,。

只需要在發(fā)布前,，創(chuàng)建一個(gè) Read the Docs 配置文件 .readthedocs.yml 就可以了。

• mkdocs 用于指定文檔使用 mkdocs 編寫(xiě)
• configuration 指定 mkdocs 文檔項(xiàng)目的配置文件
• python 為可選項(xiàng),，如果文檔需要 python 運(yùn)行環(huán)境的話可以配置,，如不需要可以不配置

更多配置請(qǐng)參考 Read the Docs 配置[13]。

然后將 mkdocs 項(xiàng)目用 github 做版本管理,，這是因?yàn)?Read the Docs 目前只支持通過(guò) github 導(dǎo)入文件,。

最后在 Read the Docs 的 Add Projcet 中，選擇 Github 中的對(duì)應(yīng)庫(kù),，按照說(shuō)明操作即可,。

如果順利將會(huì)獲得一個(gè)文檔的訪問(wèn)網(wǎng)址。

總結(jié)

大多數(shù)人討厭編寫(xiě)文檔,，不僅是因?yàn)榫帉?xiě)文檔很枯燥,，而且也是因?yàn)槲臋n形式多樣，后期制作成本很高,，容易有畏難情緒,。

利用 mkdocs 和 Read the Docs 可以讓我們將注意力和精力集中在文檔編寫(xiě)本身上，而解放了文檔后期制作的成本投入,，而且還能更方便的讓更多的人瀏覽,，讓我們的價(jià)值更大的體現(xiàn)。

期望這篇文章,，能在文檔編寫(xiě)上給你幫助和啟示,，讓自己的價(jià)值更大化，比心,。