不會(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 文章差不多，有一些需要注意的地方或是技巧需要說明一下。
站點(diǎn)布局 默認(rèn)情況下，即在不配置導(dǎo)航 (nav) 的情況下，會(huì)按照文件名，目錄結(jié)構(gòu)生成導(dǎo)航菜單
站點(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
非 markdown 文件 markdown 文件，即擴(kuò)展名為 md 的文件，會(huì)被轉(zhuǎn)化為 html。非 markdown 文件，會(huì)被原封拷貝，不做任何修改
內(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à)值更大化，比心。
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ò)的話，記得分享朋友圈讓更多的人知道！
【代碼獲取方式】