如何利用果蝇内存成为高效程序员？作者|HynekSchlawack翻译|李锐审稿人|Noah在自然界中，果蝇可以根据图形本身的一些参数，如大小、颜色、高度和图形方向等参数，完成相应视觉图形的识别并形成记忆。多年编程经验 HynekSchlawack是一位经验丰富的德国软件工程师，积极参与开源软件的开发，现为Python软件基金会成员。他说，与20世纪90年代中期首次使用AmigaBASIC相比，如今的编程技术和方法更加多样化。如果当时买一本关于计算机编程的书，这本书可能包含了99%的内容，而且书中到处都有注释和特殊标记，学习者按照书中的描述来学习和操作。 如今，关于前端Web框架的书籍可能比C64可执行程序员编写完整游戏所需的书籍还要多。另一方面，了解编写代码所需的所有信息通常只需单击鼠标即可。 如今很少有人为开发人员文档付费，Microsoft和Apple都在网络上向所有人免费提供他们的文档，更不用说免费的开源项目了。 在npm、PyPI和GitHub的时代，很难解释要求超出操作系统提供的任何东西，这曾经是一个有争议的决定，必须明智地权衡。通常依赖项随产品一起交付。 New可用性好，种类多，但是这导致生产所需的信息碎片化。 例如，人们打开了数十个选项卡，其中包含他们当前正在使用的包的文档，并且正忙于在它们之间切换以找到合适的包。在某些情况下，有数千人共享一个POP，但只有在线文件??才会成为问题，除非互联网完全消失。尤其是网络不稳定，在线搜索功能还不如没有搜索功能。 如果开发人员可以使用多种编程语言，每种语言都有庞大的子社区（即使在Python中，Flask+SQLAlchemy+Postgres与编写基于异步的Web服务器完全不同），请记住使用每个方法的参数很头疼。 Schlawack说这就是为什么在2012年发现Dash对他来说是一个改变生活的事件。API文档浏览器Dash搜索 Dash为开发人员提供了通过触摸键盘键获取所有相关API的超能力： 按下“Space”键弹出一个带有活动搜索栏的浮动窗口。 开始输入API或主题的大概名称。 从官方项目文档中的建议和土地符号中选择。 按下Esc键，悬浮窗消失，马上可以开始敲代码了，因为编辑器又获得了焦点。 如果忘记刚刚读的内容，再次按下空格键，窗口会在同一位置弹出。 这一切都非常快，在2秒内完成一次这样的往返。但它必须如此之快，这样开发人员才不会忘记他们在做什么。在这一点上，开发者可以下意识地去做。这是原生应用程序被遗忘的幸福。 而且一键获取所有API文档的功能非常强大。 开发人员在记住函数参数或类的导入路径上花费的精力越少，他在思考要解决的问题上花费的精力就越多。 虽然Dash是一个订阅费为30美元的Mac应用程序（也可作为Setapp订阅的一部分提供），但还有一个名为Zeal的免费Windows和Linux版本，以及一个名为VelocityWindows应用程序的20美元版本。当然，还有一个Emacs包可以做同样的事情：helm-dash。 以下仅关注Dash，因为这是Schlawack使用的程序，但除非另有说明，否则它适用于所有这些程序。它们的共同点是本地文档的格式。Docsets 他们都使用苹果的Docsetsbundle（文档集），这是包含HTML文档、基于XML的属性列表中的元数据和SQLite数据库中的搜索索引的目录： 如果在你的硬盘上有很多HTML文件可以转换成Dash可以使用的文档集。它只是一个带有元数据的HTML文件。由于它是您硬盘上的HTML文件，因此这一切都可以离线使用。 因此，文档集可以替换已保存在本地计算机上的文档，以便更快地访问而无需执行任何特殊操作。只需将其打包成必要的目录结构，添加一个空索引，并填写简单的元数据即可。 现在可以通过一次击键调用它们并通过另一次击键取消它们。 Schlawack表示，他每天在大量平台上开发项目。我们在这里讨论的不仅仅是编程API：Ansible角色、CSS类、HAProxy配置、Postgres（和SQL）功能......已安装的Dash文档集 虽然Python和Go核心文档随Dash一起提供，但Godoc文档可以直接通过URL添加，无论Dash多么强大：在现代软件开发的碎片化世界中，它永远无法提供所需的一切。 Sphinx 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兼容文件。 这就是Schlawack10年前开始他的doc2dash开发项目的原因。 doc2dash doc2dash是Homebrewtap提供的命令行工具，从其发布页面下载适用于Linux、macOS和Windows的预构建二进制文件之一，或从PyPI安装它。 然后，它所要做的就是将它指向一个包含intersphinx兼容文档的目录，它会做所有必要的事情，并提供一个文档集。Doc2dash转换 需要注意，它的名字是doc2dash而不是sphinx2dash。它一直被用作编写高质量transformer的框架，最早的是Sphinx和pydoctor。遗憾的是，这个希望没有实现，因为每个社区都希望使用自己的语言和工具，这是可以理解的。 然而，这些工具通常是一次性的，因此，Schlawack再次愿意与其他人合作，以增加对其他文档格式的支持。所以不要重新发明轮子，框架就在那里，只是一堆代码。 Dash和doc2dash已经存在了十多年，并且仍然看到无数的API文档选项卡打开。开发人员一直在向人们展示Dash的实际应用。 虽然这篇文章的果蝇部分到此结束，但它将继续通过分步操作方法提供帮助。如何转换和提交文档 本指南旨在教人们如何将与intersphinx兼容的文档转换为文档集，并将它们提交到Dash的用户生成的文档集注册表。 假设用户已经选择并安装了API浏览器。使用哪个并不重要，但此方法使用Dash。最后有选择地提交文档集还需要对GitHub及其拉取请求工作流程有基本的了解。 Schlawack利用本指南，从structlog开始，最终开始发布他的项目的文档集。建议用户选择兼容intershinx的项目，该项目不受Dash支持，并且用户经常访问其文档的选项卡。 所以现在你可以开始了。 获取doc2dash 如果您已经在使用Homebrew，获取doc2dash的最简单方法是使用此tap：$brewinstallhynek/tap/doc2dash 适用于x86-64和ApplesiliconforLinuxx86-65和macOS预构建，因此安装应该非常快。 除非您熟悉Python打包，否则最好的办法是从发布页面预构建二进制文件。目前，它为Linux、Windows和macOS提供二进制文件，全部基于x86-64。如果这被证明很受欢迎，希望将来会有更多。 最后，它可以从PyPI获得。推荐使用pipx，用它运行doc2dash的最简单方法是：$pipxrundoc2dash--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-typicalindex.html。所以将--index-pageindex.html添加到命令行。 添加图标 达析报告可以有图标，这些图标以虚线形式出现在达析报告名称和符号旁边。这很好，如果您在有符号的多个文档集中搜索，也有助于更快地识别文档集。 structlog有一个可爱的海狸标志，所以使用ImageMagick将标志调整为16x16像素：$magick\docs/_static/structlog_logo_transparent.png\-resize16x16\docs/_static/docset-icon.png 现在可以使用了使用--icondocset-icon.png选项将其添加到文档集中。 支持在线重定向 离线文档很棒，但有时跳转到您正在阅读的文档页面的在线版本会很有用。一个常见的原因是仔细阅读较新或较旧的版本。 Dash有菜单项“OpenOnlinePage??B”，但它需要知道文档的基本URL。可以用--online-redirect-url或-u设置。 对于ReadtheDocs上的Python包，您可以选择stable（最后一个VCS标签）或latest（当前master分支）。 如果离开离线文档，Latest可能更有意义，所以会添加：--online-redirect-urlhttps://www.structlog.org/en/latest/ 将它们放在一起 终于完成了！运行整个命令行以查看它在Dash中的外观：$doc2dash\--index-pageindex.html\--icondocs/_static/docset-icon.png\--online-redirect-urlhttps://www.structlog.org/en/latest/\docs/_build/htmlConvertingintersphinxdocs从'/Users/hynek/FOSS/structlog/docs/_build/html'到'structlog.docset'。解析文档...添加了238个索引条目.为TOC打补丁...━━━━━━━━━━━━━━━━━━━━━━━━━━━100%00:00：这是一个很棒的主页：structlog的主页 注意搜索栏中的图标，然后在带有任何锚点的任何页面上按??B，它将带您到在线文档中同一位置的最新版本。 Automation 由于要为每个新版本创建新版本的文档集，因此需要将创建自动化。structlog已经使用GitHubActions作为CI，所以它也可以用来构建文档集。 对于本地测试，将利用doc2dash作为Python项目，并使用tox环境重用测试文档本身时使用的依赖项。 tox是make和基于ini文件格式的虚拟环境管理器的组合。它最初的目的是在多个Python版本上测试Python软件，但后来变得更加强大。 Makefile最大的优点是更便携，支持内置的Python打包（无论如何构建文档都是必须的）。 安装structlog[docs]，带有可选文档依赖项的包，以及doc2dash。然后它按顺序运行命令：[testenv:docset]extras=docsdeps=doc2dashallowlist_externals=rmcptarcommands=rm-rfstructlog.docsetdocs/_buildsphinx-build-n-T-W-bhtml-d{envtmpdir}/doctrees文档docs/_build/htmldoc2dash--index-pageindex.html--icondocs/_static/docset-icon.png--online-redirect-urlhttps://www.structlog.org/en/latest/docs/_build/htmlcpdocs/_static/docset-icon@2x.pngstructlog.docset/icon@2x.pngtar--exclude='.DS_Store'-cvzfstructlog.tgzstructlog.docset 现在可以通过调用tox-eDocumentationSet构建一个文档集。doc2dash在支持高分辨率图标之前，也是将32x32像素大版的logo直接复制到docset中。 在CI中执行此操作很简单，但需要大量样板文件，因此只需链接到工作流即可。请注意末尾的上传工件操作，它允许从运行摘要下载构建的文档集。 至此，我们已经自动构建了一个不错的文档集。现在是对外分享的时候了！ 提交 在最后一步，文档集被提交到Dash的用户贡献存储库，以便其他人可以轻松地从Dash的GUI下载它。方便的是，Dash使用了每个开源爱好者可能都熟悉的整个流程的概念：GitHub拉取请求。 第一步是检查DocsetContributionChecklist。幸运的是，或者在某些情况下doc2dash已经处理了一切。 因此，转到下一步并转到https://github.com/Kapeli/Dash-User-Contributions存储库并将其克隆到您的计算机上。 首先，必须将Sample_Docset目录复制到docsets，同时重命名它。所以它的命令行是：$cp-aSample_Docsetdocsets/structlog 使用cddocsets/structlog进入目录并从那里进一步获取它。 主要步骤是添加文档集本身，但作为压缩的tar文件。贡献指南甚至提供了创建它的模板。在这个例子中，命令行是：$tar--exclude='.DS_Store'-cvzfstructlog.tgzstructlog.docset 你可能已经注意到tar-ing已经在tox文件中完成，所以只需复制它：$cp~/FOSS/structlog/structlog.tgz. 它还想在文档集中的内容中添加图标，所以从他们的文档集中复制：$cp~/FOSS/structlog/structlog.docset/icon*. 接下来在docset.html文件中填写元数据，例子中很简单：{"name":"structlog","version":"22.1.0","archive":"structlog.tgz","author":{"name":"HynekSchlawack","link":"https://github.com/hynek"},"aliases":[]} 最后，写点我们的东西是关于谁以及如何构建文档集的文档。查看其他示例后，确定了以下内容：#structlog
