企业官网建设流程全解析

NumPy 文档架构重组（NEP 44）全解：Diátaxis 四象限文档体系与仓库落地实践

【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址: https://gitcode.com/gh_mirrors/nu/numpy

导读

NEP 44（NumPy 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 提出三项核心举措：

1. 将文档重组为四类：Tutorials、How Tos、Reference Guide、Explanations；
2. 为 Tutorials 与 How-Tos 建立专门分区，并配套"如何创作新内容"的导向说明；
3. 新增 Explanations 分区，收纳关键概念与需要深度阐述的主题，其中一部分将从 Reference Guide 中迁移而来。

在后续章节可以看到，这些提议在当前仓库的doc/source目录中已经全部落地为真实结构。

二、核心框架：Diátaxis 四象限文档分类法

NEP 44 的分类依据是 Diátaxis 框架（原文引用为参考文献 [1]）。它按"读者所处的场景"把技术文档分成四类，每类对应不同的写作目的、行文语气和读者预期：

NEP 44 明确指出，这套分类的意义在于：无论是文档写作者还是读者，都能清楚判断某段信息应该放在哪里、应该以什么语气写。例如：

• 若把概念解释混入基础教程，初学者会被信息量压垮、感到疏离；
• 若把基础 how-to 塞进参考手册，资深用户将难以快速找到所需的精确信息。

Diátaxis 框架不仅指导内容归档，也指导写作与评审流程——社区新增任何文档章节时，都先用这四类之一来界定它的类型与范围。这一点在当前仓库的 howto-docs.rst（"How 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 API（module_structure、arrays、ufuncs、routines、typing）、C API（c-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）、广义 ufunc（g）ufuncs、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 tutorial（GSoD 项目，参考文献 [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 users）

• Absolute Beginners Tutorial（绝对初学者教程）
• 主 Tutorials 分区
• 面向常见任务的 How Tos
• Reference Guide（API 参考）
• Explanations（概念解释）
• F2Py Guide
• Glossary（术语表）

面向开发者/贡献者（For developers/contributors）

• Contributor's Guide（贡献者指南）
• Under-the-hood docs（底层实现文档）
• Building and extending the documentation（构建与扩展文档）
• Benchmarking（基准测试）
• NumPy Enhancement Proposals（NEP 列表）

元信息（Meta information）

• Reporting 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.rst（"How 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 提供"把事情做完"的信息，用户想要可直接复制的步骤，不一定要理解 NumPy；Tutorial 提供"感觉与手感"，用户想获得对某个方面的整体印象；两者又都区别于 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 guide，NumPy 风格在 Google 无指导或项目有偏好时兜底（例如复数用indices而非indexes、matrices而非matrixes）；docstring 采用numpydoc格式标准；C/C++ 注释用 Doxygen + Breathe 接入 Sphinx；
• 提交方式：NumPy 文档保存在源码树中，贡献者需拉取仓库、本地构建（参见 dev/howto_build_docs.rst，依赖见 requirements/doc_requirements.txt，Sphinx 配置见 doc/source/conf.py），再提交 Pull Request。

NEP 44 在 "Related work" 一节还列举了 Jupyter、Python、TensorFlow 等项目文档作为参照，指出这些项目"让每部分文档的目标读者更明确，并在各分区中预览部分内容"——这正是 NumPy 文档重组希望达到的体验。

八、后续设想与影响

NEP 44 的 "Ideas for follow-up" 提出了几个前瞻性方向，其中一部分已在仓库中变为现实：

1. Jupyter Notebook 直接作为文档：如果教程/How-To 能以 Notebook 原样提交，社区参与门槛会显著降低；若读者还能直接下载 Notebook 版本文档，则能减少对过时外部材料的使用。当前仓库主页的 jupyter_lite_config.json 与 try_examples.json 表明，文档站点已经具备交互式示例能力，而 dev/howto-docs.rst 也提到可将 Notebook 内容提交到独立的 NumPy Tutorials 页面；
2. 多语言翻译：NEP 44 期望新结构能让文档翻译更容易；
3. 降低入门门槛：官方提供高水准、可及时更新的文档，让更多用户（乃至开发者/贡献者）参与进 NumPy 社区。

从最终影响看，NEP 44 通过一次流程型提案，把 NumPy 文档从"用户/开发者混杂"的旧结构，重塑为以 Diátaxis 四象限为骨架、以读者角色为导航的现代文档体系——这一结构至今仍是当前仓库doc/source的组织基准。

九、快速索引：NEP 44 关键概念与仓库对应文件

想要深入了解提案原文，可直接阅读仓库中的 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