作者 | Hynek Schlawack

譯者 | 李睿

審校 | 諾亞

在自然界中，果蠅可以根據(jù)圖形本身所具有的一些參數(shù)來完成對相應(yīng)視覺圖形的識別并形成記憶，例如大小、顏色、高度和圖形朝向等參數(shù)。

多年的編程經(jīng)歷

　　Hynek Schlawack是一名經(jīng)驗豐富的德國軟件工程師，他積極參與開源軟件的開發(fā)，如今已成為Python軟件基金會成員。他表示，與上世紀90年代中期開始使用Amiga BASIC時相比，如今的編程技術(shù)和方法變得更加多樣化。如果那時購買一本關(guān)于計算機編程書籍，這本書可能包含99%的內(nèi)容，并且書中隨處都有注釋和專用標記，而學(xué)習(xí)者根據(jù)書中的描述邊學(xué)習(xí)邊操作。

　　如今，有關(guān)前端Web框架的書籍可能比C64可執(zhí)行文件程序員編寫完整的游戲所需的書籍還要厚。另一方面，了解編寫代碼所需的所有信息通常只需點擊鼠標搜索一下即可。

　　現(xiàn)在很少有人為開發(fā)人員文檔付費，微軟和蘋果都在網(wǎng)絡(luò)上免費為所有人提供他們的文檔，更不用說免費的開源項目。

　　在npm、PyPI和GitHub時代，很難解釋要求超出操作系統(tǒng)提供的任何東西，這曾經(jīng)是一個有爭議的決定，必須明智地權(quán)衡。通常是將依賴項與產(chǎn)品一起交付。

　　新的可用性很好，種類也很豐富，但這會導(dǎo)致生產(chǎn)所需信息的碎片化。

　　例如，人們打開了幾十個標簽，上面有他們當前使用的軟件包文檔，并忙著在它們之間進行切換以找到合適的軟件包。而在某些場合，有成千上萬的人共享一個POP，但是只有在線文件才會成為一個問題，除非互聯(lián)網(wǎng)完全消失。尤其是互聯(lián)網(wǎng)不穩(wěn)定的在線搜索功能比沒有搜索功能更糟糕。

　　如果開發(fā)人員可以使用多種編程語言，每種語言都有巨大的子社區(qū)（即使在Python中，F(xiàn)lask+SQLAlchemy+Postgres與編寫基于異步的網(wǎng)絡(luò)服務(wù)器是完全不同的事情），記住使用的每種方法的參數(shù)是讓人頭疼的事情。

　　Schlawack表示，這就是為什么2012年發(fā)現(xiàn)Dash對他來說是一件改變?nèi)松拇笫碌脑颉?/p>

API文檔瀏覽器  

Dash搜索

　　Dash讓開發(fā)人員擁有按下鍵盤按鍵就可以獲得所有相關(guān)API的超能力：

• 　　按下“空格”鍵，彈出一個浮動窗口，上面有一個激活的搜索欄。
• 　　開始輸入API或主題的大概名稱。
• 　　從建議中選擇并登陸官方項目文檔中的符號。
• 　　按下Esc鍵，浮動窗口消失，可以立即開始輸入代碼，因為編輯器再次成為焦點。
• 　　如果忘記了剛剛閱讀的內(nèi)容，再次按空格鍵，窗口會在同一位置彈出。

　　這一切都快得令人難以置信，在2秒內(nèi)完成一次這樣的往返。但它必須那么快，這樣開發(fā)人員才不會忘記在做什么。在這一點上，開發(fā)人員可以潛意識地做到。這是原生應(yīng)用程序被遺忘的幸福。

　　而按下按鍵獲得所有API文檔的能力是非常強大的。

　　開發(fā)人員在記住函數(shù)參數(shù)或類的導(dǎo)入路徑上花費的精力越少，那么在思考正在解決的問題上的精力就越多。

　　雖然Dash是一個訂閱費用為30美元的Mac應(yīng)用程序（也可作為Setapp訂閱的一部分提供），但還有一個名為Zeal的免費Windows和Linux版本，以及一個名為Velocity的20美元的Windows應(yīng)用程序。當然，還有一個Emacs包在做同樣的事情：helm-dash。

　　以下只關(guān)注Dash，因為這就是Schlawack正在使用的程序，但除非另有說明，否則它適用于所有這些。它們的共同點是本地文檔的格式。

文檔集

　　它們都使用Apple的文檔集捆綁包(docsets)，這些文檔集是包含HTML文檔、基于XML的屬性列表中的元數(shù)據(jù)和SQLite數(shù)據(jù)庫中的搜索索引的目錄：

　　如果在硬盤中有很多HTML文件，可以將其轉(zhuǎn)換為Dash可以使用的文檔集。它只是帶有元數(shù)據(jù)的HTML文件。由于它是硬盤上的HTML文件，因此所有這些都可以脫機運行。

　　因此，文檔集可以替換已經(jīng)保存在本地計算機上的文檔，以便更快訪問，而無需做任何特別的事情。只需將其打包成必要的目錄結(jié)構(gòu)，添加一個空索引，并填寫簡單的元數(shù)據(jù)。

　　現(xiàn)在可以通過一個按鍵來調(diào)用它們，然后用另一個按鍵來取消。

　　Schlawack表示，他每天都在大量平臺上開發(fā)項目。而且在這里談?wù)摰牟粌H僅是編程API：Ansible角色、CSS類、HAProxy配置、Postgres（和SQL）特性……

已安裝的Dash文檔集

　　雖然Python和Go核心文檔隨Dash一起提供，而Godoc文檔可以通過URL直接添加 ，無論Dash的功能多么強大：在現(xiàn)代軟件開發(fā)的碎片化世界中，它永遠無法提供所需要的一切。

　　Sphinx

　　Schlawack表示，對他來說最大的差距是基于Sphinx的文檔主導(dǎo)Python生態(tài)系統(tǒng)。

　　Sphinx是一個與編程語言限制的文檔編寫框架。不僅僅是API文檔或敘述性文檔：所有這些具有豐富的相互鏈接。它曾經(jīng)因?qū)eStructuredText強加給用戶而臭名昭著，但現(xiàn)在越來越多的項目使用出色的MyST包在Markdown中執(zhí)行這一操作。如果有人對Sphinx文檔的外觀有任何偏見，建議訪問Sphinx主題庫，可以看看其文檔有多漂亮。它是用Python編寫的，但被廣泛使用，包括Apple的Swift、LLVM(Clang!)項目或廣受歡迎的PHP項目。

　　它提供了準確的缺失部分：API條目、部分、詞匯表術(shù)語、配置選項、命令行參數(shù)等的索引——所有這些都以開發(fā)人員喜歡的方式分布在文檔中，但始終可以相互鏈接。如果遵循像“Diátaxis”這樣的系統(tǒng)框架，那么會覺得這非常棒。

　　從技術(shù)上說，實現(xiàn)這一點的關(guān)鍵組件只是一個擴展：interphinx。最初用于項目間鏈接（因此而得名），它提供了一個機器可讀索引供開發(fā)人員使用。該索引變得如此流行，現(xiàn)在得到了MkDocs擴展mkdocstrings和pydoctor的支持?？梢酝ㄟ^索引文件objects.inv準確識別與intershinx兼容的文檔。

　　這就是Schlawack在10年前開始采用doc2dash開發(fā)項目的原因。

　　doc2dash

　　doc2dash是一個命令行工具，可以從Homebrewtap中獲取，從其發(fā)布頁面下載適用于Linux、macOS和Windows的預(yù)構(gòu)建二進制文件之一，或從PyPI安裝。

　　然后，所要做的就是將它指向一個包含intersphinx兼容文檔的目錄，它將執(zhí)行所有必要的操作，并提供一個文檔集。

doc2dash轉(zhuǎn)換

　　需要注意，其名稱是doc2dash而不是sphinx2dash。它始終被用作編寫高質(zhì)量轉(zhuǎn)換器的框架，第一個是Sphinx和pydoctor。遺憾的是，這種希望沒有實現(xiàn)，因為可以理解的是，每個社區(qū)都想使用自己的語言和工具。

　　不過，這些工具通常是一次性的，所以Schlawack再次強調(diào)，愿意與其他人一起合作，為其他文檔格式添加支持。因此不要重新發(fā)明輪子，框架就在那里，而這只是一堆代碼。

　　Dash和doc2dash已經(jīng)存在了十多年，仍然看到打開的數(shù)不勝數(shù)的API文檔標簽頁。開發(fā)人員一直在向人們展示Dash的實際應(yīng)用。

　　雖然本文的果蠅部分到此結(jié)束，但將繼續(xù)為循序漸進的操作方法提供幫助。

如何轉(zhuǎn)換和提交文檔

　　這一指南的目的是讓人們學(xué)會如何將與intersphinx兼容的文檔轉(zhuǎn)換為文檔集，以及如何將其提交到Dash的用戶生成的文檔集注冊表。

　　假設(shè)用戶已經(jīng)選擇并安裝了API瀏覽器。使用哪一個并不重要，但這個方法使用Dash。要在最后選擇性地提交文檔集還需要對GitHub及其拉取請求工作流程有基本的了解。

　　Schlawack利用這個指南，先從structlog開始，最終開始發(fā)布其項目的文檔集。建議用戶選擇一個與intershinx兼容的項目，該項目并不受Dash支持，并且用戶經(jīng)常訪問其文檔的選項卡。

　　那么現(xiàn)在可以開始了。

　　獲取doc2dash

　　如果用戶已經(jīng)在使用Homebrew，獲取doc2dash的最簡單方法是使用這個tap：

$ brew install hynek/tap/doc2dash

　　在x86-64和Apple silicon上都有針對Linux x86-65和macOS的預(yù)構(gòu)件，因此安裝速度應(yīng)該非?？臁?/p>

　　除非熟悉Python打包方式，否則下一個最佳方式是從發(fā)布頁面預(yù)構(gòu)建二進制文件。目前，它提供適用于Linux、Windows和macOS的二進制文件，這些全部基于x86-64。如果這被證明很受歡迎，希望將來能提供更多。

　　最后，可以從PyPI中獲取它。建議使用pipx并且使用它運行doc2dash的最簡單方法是：

$ pipx run doc2dash --help

　　注：如果知道PyPy是什么，如何使用它，并計劃轉(zhuǎn)換龐大的文檔樹：在PyPy上doc2dash的速度是在CPython上的兩倍多。

　　如果對此一無所知，則可以忽略這些。

　　構(gòu)建文檔

　　接下來是doc2dash的最大問題和頻繁功能請求的來源：需要一個完整的內(nèi)置文檔。通常這意味著必須下載存儲庫，并在安裝doc2dath之前弄清楚如何構(gòu)建文檔，因為大多數(shù)文檔站點都不提供整個文檔的下載。

　　這里的建議是首先查找tox.ini或noxfile.py，并查看它是否構(gòu)建了文檔。如果沒有，可以查找readthedocs.yml，即使這讓人失望，也會尋找名為docs-requirements.txt的文件或可選的安裝目標（如docs）。最后的希望是瀏覽YAML頁面并檢查CI配置。

　　一旦設(shè)法安裝了所有依賴項，通常只需在文檔目錄中創(chuàng)建html即可。

　　在弄清楚這一點后，應(yīng)該有一個名為_build/html的目錄用于Sphinx或名為MkDocs的站點。

　　需要注意MkDocs，如果項目不使用mkdocstrings擴展，就不會有objects.inv文件，因此沒有要使用的API數(shù)據(jù)。

　　真的希望將來有更多基于MkDocs的項目添加對mkdocstrings的支持！與Sphinx一樣，它與語言無關(guān)。

　　轉(zhuǎn)換

　　最困難的一步也是最簡單的一步：將剛剛構(gòu)建的文檔轉(zhuǎn)換為文檔集。

　　所要做的就是將doc2dash指向帶有HTML文檔的目錄并等待：

$ doc2dash _build/html

　　doc2dash知道如何從intersphinx索引中提取名稱，并默認使用它（可以使用--name覆蓋它）。應(yīng)該能夠?qū)⑦@一文檔集添加到選擇的API瀏覽器中，并且一切正常。

　　如果通過--add-to-dash或-a，最終的文檔集會在完成后自動添加到Dash。如果傳遞--add-to-global或-A，它會將完成的文檔集移動到全局目錄（~/Library/ApplicationSupport/doc2dash/DocSets）并從那里添加。在創(chuàng)建文檔集時，很少在沒有-A的情況下運行doc2dash。

　　改進文檔集

　　Dash的文檔有很多關(guān)于如何改進在上一步中構(gòu)建的文檔集的建議。重要的是要注意以下五個步驟是嚴格可選的。

　　但在這種情況下，可以將文檔集提交到Dash的用戶貢獻注冊表。

　　設(shè)置主頁

　　使用Dash，始終可以搜索所有已安裝的文檔集，但有時希望限制搜索范圍。例如，當鍵入p3:（冒號很重要）時，切換到僅搜索Python3文檔集。在開始輸入之前，它會在搜索框下方為提供一個菜單，其第一項是“主頁”。

　　在轉(zhuǎn)換structlog文檔時，這個主頁是有用的索引，但通常不是想要的。當打開主頁時，通常瀏覽敘述文檔。

　　設(shè)置主頁的doc2dash選項是--index-page或-I，并采用要使用的頁面的文件名，以對應(yīng)文檔根目錄。

　　令人困惑的是，索引的文件名是genindex.html，而主頁的文件名是HTML典型的index.html。因此，將--index-pageindex.html添加到命令行。

　　添加圖標

　　文檔集可以有圖標，這些圖標顯示在文檔集名稱和符號旁邊的虛線中。這很好，并且也有助于更快地識別文檔集，如果要跨多個文檔集進行搜索，其中有一個符號。

　　structlog有一個可愛的海貍標志，所以使用ImageMagick將標志調(diào)整為16x16像素：

$ magick \
docs/_static/structlog_logo_transparent.png \
-resize 16x16 \
docs/_static/docset-icon.png

　　現(xiàn)在可以使用--icondocset-icon.png選項將它添加到文檔集中。

　　支持在線重定向

　　離線文檔很棒，但有時跳轉(zhuǎn)到正在閱讀的文檔頁面的在線版本可能會很有用。一個常見的原因是仔細閱讀更新或舊版本。

　　Dash有菜單項“OpenOnlinePage??B”，但它需要知道文檔的基本URL。可以使用--online-redirect-url或-u進行設(shè)置。

　　對于Read the Docs上的Python包，可以在stable（最后一個VCS標記）或latest（當前主分支）之間進行選擇。

　　Latest可能更有意義，如果離開離線文檔，因此將添加：

--online-redirect-url https://www.structlog.org/en/latest/

　　將所有內(nèi)容放在一起

　　終于完成了！運行整個命令行，看看它在Dash中的樣子：

$ doc2dash \
    --index-page index.html \
    --icon docs/_static/docset-icon.png \
    --online-redirect-url https://www.structlog.org/en/latest/ \
    docs/_build/html
Converting intersphinx docs from '/Users/hynek/FOSS/structlog/docs/_build/html' to 'structlog.docset'.
Parsing documentation...
Added 238 index entries.
Patching for TOCs... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00

　　這是一個精彩的主頁：

structlog的主頁

　　注意搜索欄中的圖標，然后在帶有任何錨點的任何頁面上按??B，將帶到最新版本的在線文檔中的相同位置。

　　自動化

　　由于希望為每個新版本創(chuàng)建一個新版本的文檔集，因此需要自動化創(chuàng)建。structlog已經(jīng)將GitHub Actions用作CI，因此也可以使用它來構(gòu)建文檔集。

　　對于本地測試，將利用doc2dash作為Python項目的優(yōu)勢，并使用一個tox環(huán)境來重用在測試文檔本身時使用的依賴項。

　　tox是make和基于ini文件格式的虛擬環(huán)境管理器的組合。它最初的目的是在多個Python版本上測試Python軟件，但現(xiàn)在已經(jīng)變得更加強大。

　　Makefile的最大優(yōu)點是它更易于移植，并且支持內(nèi)置的Python打包（無論如何這對于構(gòu)建文檔都是必需的）。

　　安裝structlog[docs]，即具有可選文檔依賴項的包，加上doc2dash。然后它按順序運行命令：

[testenv:docset]
extras = docs
deps = doc2dash
allowlist_externals =
    rm
    cp
    tar
commands =
    rm -rf structlog.docset docs/_build
    sphinx-build -n -T -W -b html -d {envtmpdir}/doctrees docs docs/_build/html
    doc2dash --index-page index.html --icon docs/_static/docset-icon.png --online-redirect-url https://www.structlog.org/en/latest/ docs/_build/html
    cp docs/_static/docset-icon@2x.png structlog.docset/icon@2x.png
    tar --exclude='.DS_Store' -cvzf structlog.tgz structlog.docset

　　現(xiàn)在可以通過調(diào)用tox-e文檔集來構(gòu)建一個文檔集。在doc2dash支持高分辨率圖標之前，它還將32x32像素大的徽標版本直接復(fù)制到文檔集中。

　　在CI中這樣做很簡單，但需要大量的樣板文件，所以只鏈接到工作流。注意最后的上傳工件操作，它允許從運行摘要下載構(gòu)建的文檔集。

　　此時，有了一個自動構(gòu)建的很棒的文檔集。現(xiàn)在是對外分享的時候了！

　　提交

　　在最后一步中，會將文檔集提交到Dash的用戶貢獻的存儲庫，以便其他人可以從Dash的GUI輕松下載它。方便的是，Dash使用每個開源愛好者可能熟悉的整個過程的概念：GitHub拉取請求。

　　第一步是檢查Docset Contribution Checklist。幸運的是，或者在某些情況下是doc2dash，已經(jīng)處理好了一切。

　　因此進行下一步，并進入https://github.com/Kapeli/Dash-User-Contributions存儲庫，并將其克隆的計算機上。

　　首先，必須將Sample_Docset目錄復(fù)制到docsets，并在執(zhí)行此操作時重命名它。因此，其命令行是：

$ cp -a Sample_Docset docsets/structlog

　　使用cddocsets/structlog進入目錄并從那里進一步獲取它。

　　主要步驟是添加文檔集本身，但要作為一個gzipped tar文件。貢獻指南甚至提供了創(chuàng)建它的模板。在這個例子中，命令行是：

$ tar --exclude='.DS_Store' -cvzf structlog.tgz structlog.docset

　　可能已經(jīng)注意到已經(jīng)在tox文件中完成了tar-ing，所以只需要復(fù)制它：

$ cp ~/FOSS/structlog/structlog.tgz .

　　它還希望將圖標添加到文檔集中的內(nèi)容中，因此從它們的文檔集中復(fù)制：

$cp~/FOSS/structlog/structlog.docset/icon*。

　　接下來，在docset.html文件中填寫元數(shù)據(jù)，這在例子中很簡單：

{
    "name": "structlog",
    "version": "22.1.0",
    "archive": "structlog.tgz",
    "author": {
        "name": "Hynek Schlawack",
        "link": "https://github.com/hynek"
    },
    "aliases": []
}

　　最后，寫一些關(guān)于我們是誰以及如何構(gòu)建文檔集的文檔。在查看了其他示例后，確定了以下內(nèi)容：

# structlog
<https://www.structlog.org/>
Maintained by [Hynek Schlawack](https://github.com/hynek/).
## Building the Docset
### Requirements
- Python 3.10
- [*tox*](https://tox.wiki/)
### Building
1. Clone the [*structlog* repository](https://github.com/hynek/structlog).
2. Check out the tag you want to build.
3. `tox -e docset` will build the documentation and convert it into `structlog.docset` in one step.

　　tox技巧正在得到回報——不必向任何人解釋Python打包！

　　不要忘記從示例文檔集中刪除不使用的內(nèi)容：

$ rm -r versions Sample_Docset.tgz

　　終于完成了！檢查一下更改：

$ git checkout -b structlog
$ git add docsets/structlog
$ git commit -m "Add structlog docset"
[structlog 33478f9] Add structlog docset
 5 files changed, 30 insertions(+)
 create mode 100644 docsets/structlog/README.md
 create mode 100644 docsets/structlog/docset.json
 create mode 100644 docsets/structlog/icon.png
 create mode 100644 docsets/structlog/icon@2x.png
 create mode 100644 docsets/structlog/structlog.tgz
 $ git push -u

這看起來不錯，那么現(xiàn)在是提出拉取請求的時候了！　　

在幾個小時之后將出現(xiàn)這一圖像：

在Dash中貢獻的structlog文檔集

　　終于獲得成功，現(xiàn)在每個人都可以下載structlog文檔集。

結(jié)束語

　　Schlawack表示，希望本文既激發(fā)了用戶對API文檔瀏覽器的興趣，又揭開了創(chuàng)建自己文檔集的神秘面紗。而其目標是幫助在完成工作時必須牢記的所有軟件包的程序員。

　　他希望這篇文章能激發(fā)人們向doc2dash添加更多格式，以便更多的程序員能夠享受觸手可及的API文檔的樂趣。

　　在發(fā)表這篇文章后，Schlawack的另一個期望是Zeal重新煥發(fā)活力。根據(jù)行業(yè)媒體的報道，Zeal最后一次更新可以追溯到四年前，因為這是一個開源項目，如果能夠獲得新的客戶，就可能讓用戶在所有平臺上擁有良好的API瀏覽器。

　　原文鏈接：

??　　https://hynek.me/articles/productive-fruit-fly-programmer/??