不會(huì)寫文檔，叫什么高級(jí)程序員！

文 | 李曉飛

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

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

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

文檔框架

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

對(duì)于 Python 有專門文檔標(biāo)記語言 reStructuredText（RST）[7]，常見的 Python 各種庫和工具的幫助文檔基本都是用 RST 所寫。

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

例如 Scrapy 的文檔

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

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

Mkdocs

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

環(huán)境搭建

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

pip install mkdocs

查看 MkDocs 版本：

mkdocs --version

mkdocs, version 1.2.1 from <...>\lib\site-packages\mkdocs (Python 3.9)

如上，即 MkDocs 安裝正常了。

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

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

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

mkdocs new testdocs

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

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

mkdocs.yml 為配置文件

docs 文件夾中為文檔文件目錄，文件使用 markdown 編寫。

文檔預(yù)覽

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

mkdocs serve

INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 0.16 seconds
INFO     -  [18:16:18] Serving on http://127.0.0.1:8000/

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

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

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

編寫文檔

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

配置

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

site_name: MkLorum
site_url: https://example.com/
nav:
    - Home: 'index.md'
    - About: 'markdown.md'
theme: readthedocs

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

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

nav:
    - Home: 'index.md'
    - 'User Guide':
        - 'Writing your docs':
            - Menu1 : 'menu1.md'
            - Menu2 : 'menu2.md'
        - 'Styling your docs': './style/styling-your-docs.md'
    - About:
        - 'License': 'license.md'
        - 'Release Notes': 'release-notes.md'

效果如下：

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

一些約定

文檔編寫過程和寫一般的 markdown 文章差不多，有一些需要注意的地方或是技巧需要說明一下。

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

2. 站點(diǎn)首頁 默認(rèn)情況下，必須創(chuàng)建一個(gè) index.md 作為站點(diǎn)首頁。同時(shí)也支持 README.md 作為首頁，會(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)

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

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

mkdocs build

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

發(fā)布

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

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

自主發(fā)布

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

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

location /docs/ {
    alias /home/www/site/;
}

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

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

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

Read the Docs

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

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

Read the Docs 提供公開和商業(yè)兩種版本，商業(yè)版可以發(fā)布私有文檔，否則只能發(fā)布公開的文檔，可以根據(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 就可以了。

# Required
version: 2

mkdocs:
  configuration: mkdocs.yml

# Optionally set the version of Python and requirements required to build your docs
python:
   version: 3.7
   install:
   - requirements: docs/requirements.txt

• mkdocs 用于指定文檔使用 mkdocs 編寫
• 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 目前只支持通過 github 導(dǎo)入文件。

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

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

總結(jié)

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

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

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

[1]

markdown: https://markdown.com.cn/basic-syntax/

[2]

WordPress: https://cn.wordpress.org/

[3]

Hexo: https://hexo.io/zh-cn/index.html

[4]

Javadoc: https://en.wikipedia.org/wiki/Javadoc

[5]

pydoc: https://docs.python.org/3/library/pydoc.html

[6]

Python-sphinx: https://www.sphinx-doc.org/en/master/usage/quickstart.html

[7]

reStructuredText（RST）: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

[8]

Requests: https://docs.python-requests.org/zh_CN/latest/

[9]

Flask: https://flask.palletsprojects.com/en/2.0.x/

[10]

Scrapy: https://docs.scrapy.org/en/latest/

[11]

mkdocs: https://www.mkdocs.org/

[12]

Read the Docs: https://readthedocs.org/

[13]

Read the Docs 配置: https://docs.readthedocs.io/en/stable/config-file/v2.html

PS：公號(hào)內(nèi)回復(fù)「Python」即可進(jìn)入Python 新手學(xué)習(xí)交流群，一起 100 天計(jì)劃！

老規(guī)矩，兄弟們還記得么，右下角的 “在看” 點(diǎn)一下，如果感覺文章內(nèi)容不錯(cuò)的話，記得分享朋友圈讓更多的人知道！

【代碼獲取方式】

識(shí)別文末二維碼，回復(fù)：python