NumPy 文档架构重组NEP 44全解Diátaxis 四象限文档体系与仓库落地实践【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址: https://gitcode.com/gh_mirrors/nu/numpy导读NEP 44NumPy Enhancement Proposal 44标题为Restructuring the NumPy documentation是 NumPy 官方提出的文档体系重组方案其核心是借鉴 Daniele Procida 的 Diátaxis 框架把文档划分为Tutorials教程、How-to guides操作指南、Explanations概念解释、Reference guide参考手册四类并为用户、开发者、元信息三类读者分别组织入口。本文以 nep-0044-restructuring-numpy-docs.rst 为骨架结合当前仓库doc/source目录的实际落地结构展开读完本文你将掌握 NEP 44 的完整背景、四类文档的定位与写作规范并能对照仓库源码树理解这次重组最终如何落实为可构建、可贡献的文档体系。一、NEP 44 是什么动机与背景NEP 44 由 Ralf Gommers、Melissa Mendonça、Mars Lee 共同提出创建于 2020-02-11状态为Accepted已接受类型属于Process流程类 NEP——也就是说它不是关于某个 NumPy API 的设计提案而是关于 NumPy 项目自身的文档组织方式的治理提案。提案动机非常直白NumPy 官方文档的旧版组织方式令人困惑且缺乏逻辑最典型的问题是用户文档与开发者文档混在一起。这带来的直接后果是对初学者而言文档难以发现该从哪学起——除非用户对 Reference参考手册的结构已经有清晰认知否则很难定位到适合自己的内容对资深用户而言混入大量教程式内容会让参考手册变得冗长难以快速检索所需信息网络上存在大量非官方的 NumPy 教程且更新滞后。搜索引擎检索 NumPy Tutorial 时用户常常先命中过时的第三方教程而非官方最新文档。构建一套高质量、易于维护的官方文档基础设施正是为了缓解这一问题。因此NEP 44 提出三项核心举措将文档重组为四类Tutorials、How Tos、Reference Guide、Explanations为 Tutorials 与 How-Tos 建立专门分区并配套如何创作新内容的导向说明新增 Explanations 分区收纳关键概念与需要深度阐述的主题其中一部分将从 Reference Guide 中迁移而来。在后续章节可以看到这些提议在当前仓库的doc/source目录中已经全部落地为真实结构。二、核心框架Diátaxis 四象限文档分类法NEP 44 的分类依据是 Diátaxis 框架原文引用为参考文献 [1]。它按读者所处的场景把技术文档分成四类每类对应不同的写作目的、行文语气和读者预期文档类别定位典型读者场景写作特征Tutorials教程学习导向想上手、获得手感的新手循序渐进、有完整步骤与示例数据目标是让读者建立整体认知How-to guides操作指南任务导向想立刻搞定一件事的用户直奔主题、给出可复制的步骤不要求读者理解底层原理Explanations概念解释理解导向想弄懂为什么的读者深入剖析概念、设计决策与技术约束注重背景与上下文Reference guide参考手册信息导向想查某个 API 的权威定义的用户完整、准确、权威地描述函数/类/参数无需铺陈背景NEP 44 明确指出这套分类的意义在于无论是文档写作者还是读者都能清楚判断某段信息应该放在哪里、应该以什么语气写。例如若把概念解释混入基础教程初学者会被信息量压垮、感到疏离若把基础 how-to 塞进参考手册资深用户将难以快速找到所需的精确信息。Diátaxis 框架不仅指导内容归档也指导写作与评审流程——社区新增任何文档章节时都先用这四类之一来界定它的类型与范围。这一点在当前仓库的 howto-docs.rstHow to contribute to the NumPy documentation中得到了直接呼应该页面明确写道有四类文档tutorial、how-to guide、explanation、reference这一洞见属于 Daniele Procida 的 Diátaxis 框架当你开始撰写或提议一篇文档时先想清楚它属于哪一类。三、四类文档的现状评估与建设方向NEP 44 逐类评估了 NumPy 文档的家底并给出每类的建设重点。3.1 Reference guide参考手册已经比较完整属于增量优化NumPy 的参考手册相当完备所有函数都有文档、多数带示例、多数通过See Also段良好地交叉引用。NEP 44 的判断是参考手册的进一步完善属于可由许多人并行推进的增量工作。同时它指出一个结构性问题参考手册里混入了大量解释性内容这些内容应当被迁移到专门的 Explanations 分区让参考手册回归查 API的纯粹定位。对照当前仓库reference/index.rst 确实呈现了精炼的参考手册骨架Python APImodule_structure、arrays、ufuncs、routines、typing、C APIc-api/index以及其他主题array API、SIMD、线程安全等不再承载长篇幅的概念教学。3.2 How-to guides操作指南数量偏少亟待扩充NEP 44 指出 NumPy 的 how-to 一直很少并给出了具体的待补充主题清单并行化用threadpoolctl控制 BLAS 多线程、使用 multiprocessing、随机数生成等数据存储与加载.npy/.npz格式、文本格式、Zarr、HDF5、Bloscpack 等性能内存布局、性能剖析、与 Numba、Cython 或 Pythran 配合使用编写泛化代码让代码同时兼容 NumPy、Dask、CuPy、pydata/sparse 等数组库。落地到当前仓库user/howtos_index.rst 已经建立了专门的NumPy how-tos分区内含 how-to-how-to如何写 how-to 的元指南、how-to-io、how-to-index、how-to-verify-bug、how-to-partition、how-to-print 等任务型页面与 NEP 44 的规划一一对应。3.3 Explanations概念解释基础概念已有积累需系统化NEP 44 认为NumPy 在索引indexing、向量化vectorization、广播broadcasting、广义 ufuncgufuncs、dtype 等基础概念上已有相当体量的内容但组织不够清晰且常常与教程、how-to 混杂。它点名的可扩展解释主题包括Copies vs. Views拷贝与视图BLAS 及其他线性代数库的工作原理Fancy indexing花式索引。落地到当前仓库user/basics.rst 以 NumPy fundamentals 为总纲把概念解释集中为系列页面basics.creation、basics.indexing、basics.io、basics.types、basics.broadcasting、basics.copies、basics.strings、basics.rec、basics.ufuncs。该页面开宗明义这些文档澄清 NumPy 中的概念、设计决策与技术约束是理解 NumPy 基本思想与哲学的好地方——正是 NEP 44 期望 Explanations 承担的职责。3.4 Tutorials教程缺口最大空间广阔NEP 44 直言教程是潜力最大的领域。当时已有的新成果是 Anne Bonner 的NumPy for absolute beginners tutorialGSoD 项目参考文献 [3]此外还需要覆盖不同 Python/NumPy 经验水平的教程并建议用有吸引力的真实数据集替代合成随机数据。NEP 44 给出的教程创意包括仅用 NumPy 实现 Conway 生命游戏用掩码数组处理时间序列中的缺失数据用傅里叶变换分析 Keeling 曲线大气 CO₂ 浓度几十年的实测数据并做外推地理空间数据如用 lat/lon/time 堆叠数组按年绘制地图文本数据与 dtype 结合例如用不同人物的演讲稿组织成(n_speech, n_sentences, n_words)形状的数组。NEP 44 还建议撰写一份How to write a tutorial文档帮助社区贡献高质量教程。落地到当前仓库user/index.rst 的 Getting started 分区已包含 whatisnumpy、quickstart、absolute_beginners与 NEP 44 提出的Absolute Beginners Tutorial 主 Tutorials 分区结构吻合。四、数据集策略优先使用 scipy.datasets为了让教程使用有趣的数据必须让所有用户都能访问到这些数据——要么打进 NumPy 本体要么放在独立包中。NEP 44 明确否定了前者在不显著增大 NumPy 体积的前提下很难做到。因此定下原则只要可能文档页面应使用scipy.datasets包中的示例数据。这一决策保证了 NumPy 本体保持轻量同时教程数据仍可通过成熟的科学计算生态获取。五、目标文档结构用户 / 开发者 / 元信息三层NEP 44 在 Implementation 一节给出了重组后的完整站点地图分为三大块面向用户For usersAbsolute Beginners Tutorial绝对初学者教程主 Tutorials 分区面向常见任务的 How TosReference GuideAPI 参考Explanations概念解释F2Py GuideGlossary术语表面向开发者/贡献者For developers/contributorsContributors Guide贡献者指南Under-the-hood docs底层实现文档Building and extending the documentation构建与扩展文档Benchmarking基准测试NumPy Enhancement ProposalsNEP 列表元信息Meta informationReporting bugs报告缺陷Release Notes版本发布说明About NumPy项目介绍License许可证把这一蓝图与当前仓库的 doc/source/index.rst 对照可以看到重组已经基本完成主页 toctree 直接列出User Guide、API reference、Building from source、Development、release五个入口与 NEP 44 的三层结构一一对应用户侧user/index.rst入门、fundamentals、how-tos、高级用法与互操作、f2py/index.rst、glossary.rst开发者侧dev/index.rst贡献者指南、dev/underthehood.rst、dev/howto_build_docs.rst、benchmarking.rst 以及doc/neps目录下的全部 NEP 提案元信息侧release.rst版本发布说明、license.rst、numpy_2_0_migration_guide.rst。同时NEP 44 在 Backward compatibility 一节已经预告重组将实质上要求全面重写链接和部分现有内容社区的意见对识别不应被破坏的关键链接和页面很有帮助——这也是重组过程中对已有 URL/交叉引用的基本保护策略。六、How-to 与 Tutorial 的边界仓库里的写作规范NEP 44 强调四类文档要有明确的边界与语气而当前仓库把这一理念进一步落实成了可执行的写作指南。最典型的例子是 how-to-how-to.rstHow to write a NumPy how-to它用陌生人问路的比喻定义了 how-to 的写法给出简短而明确的回答如三公里外右转到 Hayseed Road加油站就在左手边。可以补充对新手有帮助的细节比如地标名但不要加入无关信息不要顺带讲 Route 7 的走法也不要解释小镇为什么只有一个加油站如果有相关背景用链接引导把从 Route 7 怎么走为什么加油站这么少分别链到教程、解释、参考或另一篇 how-to可以委托Delegate如果信息已有现成且足够简短的文档直接链接即可最多加一句引子宽问题要收窄并重定向一个How to 看景点的页面应链向一组更窄的 how-to历史建筑、观景台、镇中心更窄的页面还可以再链向更窄的条目法院、市政厅——这样既服务了问题宽泛的用户也服务了问题精确的用户步骤多就拆分把长流程拆成独立 how-to 并互相链接同时使用子标题帮助读者定位与续读。该文档还正面回答了How-to 和 Tutorial 不是一回事吗社区按 Diátaxis 分类法明确区分二者——How-to 提供把事情做完的信息用户想要可直接复制的步骤不一定要理解 NumPyTutorial 提供感觉与手感用户想获得对某个方面的整体印象两者又都区别于 Explanations为了理解而深入与 Reference对具体对象的完整权威数据。这份规范正是 NEP 44 How to write a tutorial 文档设想的延伸仓库用同一套方法写了一份how to 写 how-to的元文档成为贡献者创作新内容的起点。七、如何参与与构建文档贡献与本地构建NEP 44 的落地离不开持续的社区贡献。当前仓库的 dev/howto-docs.rst 明确把 NEP 44 定位为文档的正式路线图它指出了我们文档需要帮助的领域并列出我们希望增加的若干内容。该页面给出的贡献路径包括修缺陷Contributing fixes最高优先级是技术性错误docstring 缺参数、函数/参数/方法描述有误与结构性缺陷如失效链接可直接提 PR拼写与措辞问题欢迎报告但可能无法及时处理新增页面Contributing new pages先在 numpy-discussion 邮件列表上交流想法或开 issue 指出缺口间接贡献Contributing indirectly写博客教程、录视频、在问答社区回答问题同样是贡献写作规范用户文档遵循 Google developer documentation style guideNumPy 风格在 Google 无指导或项目有偏好时兜底例如复数用indices而非indexes、matrices而非matrixesdocstring 采用numpydoc格式标准C/C 注释用 Doxygen Breathe 接入 Sphinx提交方式NumPy 文档保存在源码树中贡献者需拉取仓库、本地构建参见 dev/howto_build_docs.rst依赖见 requirements/doc_requirements.txtSphinx 配置见 doc/source/conf.py再提交 Pull Request。NEP 44 在 Related work 一节还列举了 Jupyter、Python、TensorFlow 等项目文档作为参照指出这些项目让每部分文档的目标读者更明确并在各分区中预览部分内容——这正是 NumPy 文档重组希望达到的体验。八、后续设想与影响NEP 44 的 Ideas for follow-up 提出了几个前瞻性方向其中一部分已在仓库中变为现实Jupyter Notebook 直接作为文档如果教程/How-To 能以 Notebook 原样提交社区参与门槛会显著降低若读者还能直接下载 Notebook 版本文档则能减少对过时外部材料的使用。当前仓库主页的 jupyter_lite_config.json 与 try_examples.json 表明文档站点已经具备交互式示例能力而 dev/howto-docs.rst 也提到可将 Notebook 内容提交到独立的 NumPy Tutorials 页面多语言翻译NEP 44 期望新结构能让文档翻译更容易降低入门门槛官方提供高水准、可及时更新的文档让更多用户乃至开发者/贡献者参与进 NumPy 社区。从最终影响看NEP 44 通过一次流程型提案把 NumPy 文档从用户/开发者混杂的旧结构重塑为以 Diátaxis 四象限为骨架、以读者角色为导航的现代文档体系——这一结构至今仍是当前仓库doc/source的组织基准。九、快速索引NEP 44 关键概念与仓库对应文件NEP 44 概念说明仓库中的落地位置四类文档分类DiátaxisTutorials / How-tos / Explanations / Referencedoc/source/user/how-to-how-to.rstReference guide 现状完整、增量优化、解释内容迁出doc/source/reference/index.rstHow-to 扩充清单并行化、数据存储、性能、泛化代码doc/source/user/howtos_index.rstExplanations 系列copies/views、broadcasting、ufuncs 等概念doc/source/user/basics.rstTutorials 分区初学者教程、快速上手doc/source/user/index.rst三层站点地图用户 / 开发者 / 元信息doc/source/index.rst数据集策略优先使用scipy.datasetsNEP 44 Data sets 一节文档贡献与构建NEP 44 为文档路线图doc/source/dev/howto-docs.rst、doc/source/dev/howto_build_docs.rst想要深入了解提案原文可直接阅读仓库中的 nep-0044-restructuring-numpy-docs.rst该目录下还保存着从 NEP 1 到 NEP 57 的完整提案集如 nep-0029-deprecation_policy.rst、nep-0045-c_style_guide.rst共同构成了 NumPy 项目治理与工程决策的完整历史档案。【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址: https://gitcode.com/gh_mirrors/nu/numpy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考