作者 | 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/
