作者 | Hynek Schlawack

譯者 | 李睿

審校 | 諾亞

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

多年的編程經歷

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

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

　　現在很少有人為開發人員文檔付費，微軟和蘋果都在網絡上免費為所有人提供他們的文檔，更不用說免費的開源項目。

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

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

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

　　如果開發人員可以使用多種編程語言，每種語言都有巨大的子社區（即使在Python中，Flask+SQLAlchemy+Postgres與編寫基于異步的網絡服務器是完全不同的事情），記住使用的每種方法的參數是讓人頭疼的事情。

　　Schlawack表示，這就是為什么2012年發現Dash對他來說是一件改變人生的大事的原因。

API文檔瀏覽器  

Dash搜索

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

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

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

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

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

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

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

文檔集

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

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

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

　　現在可以通過一個按鍵來調用它們，然后用另一個按鍵來取消。

　　Schlawack表示，他每天都在大量平臺上開發項目。而且在這里談論的不僅僅是編程API：Ansible角色、CSS類、HAProxy配置、Postgres（和SQL）特性……

已安裝的Dash文檔集

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

　　Sphinx

　　Schlawack表示，對他來說最大的差距是基于Sphinx的文檔主導Python生態系統。

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

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

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

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

　　doc2dash

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

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

doc2dash轉換

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

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

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

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

如何轉換和提交文檔

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

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

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

　　那么現在可以開始了。

　　獲取doc2dash

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

$ brew install hynek/tap/doc2dash

　　在x86-64和Apple silicon上都有針對Linux x86-65和macOS的預構件，因此安裝速度應該非常快。

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

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

$ pipx run doc2dash --help

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

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

　　構建文檔

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

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

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

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

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

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

　　轉換

　　最困難的一步也是最簡單的一步：將剛剛構建的文檔轉換為文檔集。

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

$ doc2dash _build/html

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

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

　　改進文檔集

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

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

　　設置主頁

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

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

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

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

　　添加圖標

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

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

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

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

　　支持在線重定向

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

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

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

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

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

　　將所有內容放在一起

　　終于完成了！運行整個命令行，看看它在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，將帶到最新版本的在線文檔中的相同位置。

　　自動化

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

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

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

　　Makefile的最大優點是它更易于移植，并且支持內置的Python打包（無論如何這對于構建文檔都是必需的）。

　　安裝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

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

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

　　此時，有了一個自動構建的很棒的文檔集。現在是對外分享的時候了！

　　提交

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

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

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

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

$ cp -a Sample_Docset docsets/structlog

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

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

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

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

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

　　它還希望將圖標添加到文檔集中的內容中，因此從它們的文檔集中復制：

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

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

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

　　最后，寫一些關于我們是誰以及如何構建文檔集的文檔。在查看了其他示例后，確定了以下內容：

# 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打包！

　　不要忘記從示例文檔集中刪除不使用的內容：

$ 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

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

在幾個小時之后將出現這一圖像：

在Dash中貢獻的structlog文檔集

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

結束語

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

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

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

　　原文鏈接：

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