NEP 44 — 重构 NumPy 文档#

作者:

Ralf Gommers

作者:

Melissa Mendonça

作者:

Mars Lee

状态:

已接受

类型:

流程

创建日期:

2020-02-11

决议:

https://mail.python.org/pipermail/numpy-discussion/2020-March/080467.html

摘要#

本文档提出对 NumPy 文档进行形式和内容上的重构，目标是使其对初学者和经验丰富的用户更具组织性和可发现性。

动机与范围#

最新的文档首页请参见此处。目前的组织结构相当混乱且不合逻辑（例如，用户和开发者文档混杂）。我们提出以下建议：

  • 将文档重组为[1]中提及的四个类别，即 教程 (Tutorials)、操作指南 (How Tos)、参考指南 (Reference Guide) 和 解释 (Explanations)（更多内容见下文）。

  • 为教程和操作指南创建专门的章节，包括如何创建新内容的指导；

  • 添加一个解释章节，用于需要更深入描述的关键概念和技术，其中一些将从参考指南中重新组织过来。

用途与影响#

文档是任何软件项目，尤其是开源项目的基本组成部分。对于 NumPy 来说，许多初学者可能会因为当前的文档结构感到沮丧，因为它很难发现应该学习什么（除非用户清楚地知道在参考文档中查找什么，但这并非总是如此）。

在任何搜索引擎上搜索“NumPy 教程”的结果也反映了对此类内容的需求。拥有使用最新内容和技术编写的官方高级文档，必将意味着更多用户（以及开发者/贡献者）参与到 NumPy 社区中。

向后兼容性#

此次重构将有效地要求完全重写链接和部分现有内容。社区的意见将有助于识别不应中断的关键链接和页面。

详细描述#

如文章[1]中所讨论，文档内容有四类：

  • 教程

  • 操作指南

  • 解释

  • 参考指南

我们建议在添加新文档章节时，将这些类别用作我们（编写和审查）的依据。

这样做的原因是为了让开发者/文档编写者和用户都能更清楚地了解每条信息应该放在哪里，以及每个文档的范围和语调。例如，如果解释与基本教程混在一起，初学者可能会感到不知所措和疏远。另一方面，如果参考指南包含基本的“操作方法”，经验丰富的用户可能难以快速找到他们需要的信息。

目前，互联网上有许多关于 NumPy 或使用 NumPy 的博客和教程。其中一个问题是，如果用户搜索这些信息，他们可能会在找到当前官方文档之前，先看到过时的（非官方）教程。这可能会特别令人困惑，尤其是对于初学者。建立更好的文档基础设施也旨在解决这个问题，通过向用户提供高级、最新且易于更新的官方文档。

每种文档内容的状态和想法#

参考指南#

NumPy 有一个相当完整的参考指南。所有函数都有文档，大多数有示例，并且大多数与 参见 (See Also) 部分有良好的交叉链接。进一步改进参考指南是许多人可以（并且正在）进行的增量工作。然而，参考指南中有很多解释。这些可以移到文档中更专门的“解释”章节。

操作指南#

NumPy 并没有很多操作指南。“子类化和数组鸭子类型”一节可能是一个操作指南的例子。可以添加的其他内容包括：

  • 并行化（使用 threadpoolctl 控制 BLAS 多线程，使用多进程，随机数生成等）

  • 存储和加载数据（.npy/.npz 格式，文本格式，Zarr，HDF5，Bloscpack 等）

  • 性能（内存布局，性能分析，与 Numba、Cython 或 Pythran 的使用）

  • 编写适用于 NumPy、Dask、CuPy、pydata/sparse 等的通用代码

解释#

目前有相当数量关于 NumPy 基本概念的内容，如索引、向量化、广播、(g)ufuncs 和 dtypes。这些内容可以更好地组织和阐明，以确保它们真正是概念解释，而不是与教程或操作指南式的内容混淆。

除了这些 NumPy 基本概念之外，很少有其他内容的解释。

可以扩展的概念示例：

  • 副本与视图；

  • BLAS 和其他线性代数库；

  • 花式索引。

此外，参考指南中有许多解释，应将其移至这个新的专用“解释”章节。

教程#

编写更好的教程有很大的空间。我们有一个新的 NumPy 绝对初学者教程 [3]（Anne Bonner 的 GSoD 项目）。此外，我们需要一些针对不同 Python 和 NumPy 经验水平的教程。这可以通过使用引人入胜的数据集、想法或故事来完成。例如，使用 Keeling 曲线（数十年的空气中二氧化碳浓度测量值）而不是合成随机数据，进行多项式和 numpy.linalg 中函数的曲线拟合。

教程的想法（这些是合理的类型，不一定是我们要实现的具体主题）：

  • 仅用 NumPy 实现康威生命游戏（注意：已在Nicolas Rougier 的书中）

  • 使用掩码数组处理时间序列测量中的缺失数据

  • 使用傅里叶变换分析 Keeling 曲线数据并进行外推。

  • 地理空间数据（例如，通过堆叠数组使用纬度/经度/时间为每年创建地图，如 gridMet 数据）

  • 使用文本数据和 dtypes（例如，使用不同人物的演讲，形状为 (n_speech, n_sentences, n_words)）

Software Carpentry 讲师培训材料中的 准备教学 (Preparing to Teach) 文档[2]很好地总结了如何编写有效的教学计划（教程会非常相似）。除了添加新教程之外，我们还提议编写一份 如何编写教程 (How to write a tutorial) 文档，这将有助于用户向文档贡献新的高质量内容。

数据集#

在 NumPy 文档中使用有趣的数据需要让所有用户都能访问这些数据，无论是在 NumPy 内部还是在单独的包中。前者不是最佳方案，因为它很难在不显著增加 NumPy 大小的情况下实现。

尽可能地，文档页面应使用来自 scipy.datasets 包的示例。

实现#

目前，NumPy 文档可能令人困惑，尤其是对于初学者。我们的提案是按以下结构重组文档：

  • 面向用户

    • 绝对初学者教程

    • 主教程章节

    • NumPy 常见任务的操作指南

    • 参考指南（API 参考）

    • 解释

    • F2Py 指南

    • 术语表

  • 面向开发者/贡献者

    • 贡献者指南

    • 内部实现文档

    • 构建和扩展文档

    • 性能基准测试

    • NumPy 增强提案

  • 元信息

    • 报告错误

    • 发布说明

    • 关于 NumPy

    • 许可证

后续想法#

除了在一定程度上重写当前文档外，理想情况是拥有一个技术基础设施，允许社区做出更多贡献。例如，如果 Jupyter Notebooks 可以直接作为教程或操作指南提交，这可能会吸引更多贡献者并扩大 NumPy 社区。

同样，如果人们能够以 Notebook 格式下载部分文档，这无疑将意味着人们在学习 NumPy 时会更少使用过时的材料。

如果新的文档结构能使翻译更容易，那也将很有趣。

讨论#

关于此 NEP 的讨论可在 NumPy 邮件列表中找到：

参考文献和脚注#