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] 中提到的四类，即教程、操作方法、参考指南和解释（更多内容见下文）。

  • 创建专门用于教程和操作方法的部分，包括关于如何创建新内容的指导；

  • 添加一个解释部分，用于解释需要更深入描述的关键概念和技术，其中一些内容将从参考指南中重新排列。

用法和影响#

文档是任何软件项目，尤其是开源项目的基础部分。就 NumPy 而言，许多初学者可能会因为文档的当前结构而感到沮丧，因为很难发现学习的内容（除非用户清楚地知道在参考文档中查找什么，而情况并非总是如此）。

查看在任何搜索引擎上搜索“NumPy 教程”的结果，也可以了解对这类内容的需求。拥有使用最新内容和技术编写的官方高级文档，肯定意味着会有更多用户（和开发者/贡献者）参与 NumPy 社区。

向后兼容性#

重构实际上需要完全重写链接和一些当前内容。社区的投入将有助于识别不应破坏的关键链接和页面。

详细描述#

如文章 [1] 中所述，文档内容分为四类：

  • 教程

  • 操作方法指南

  • 解释

  • 参考指南

我们建议在添加新的文档章节时使用这些类别（用于编写和审查）。

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

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

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

参考指南#

NumPy 有一个相当完整的参考指南。所有函数都有文档记录，大多数都有示例，大多数都与另请参见部分很好地交叉链接。进一步改进参考指南是一项可以由许多人完成（并且正在完成）的增量工作。但是，参考指南中有很多解释。这些可以移动到文档中更专门的解释部分。

操作方法指南#

NumPy 没有很多操作方法。子类化和数组鸭子类型部分可能是操作方法的一个示例。其他可以添加的操作方法包括：

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

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

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

  • 编写与 NumPy、Dask、CuPy、pydata/sparse 等一起使用的通用代码。

解释#

关于 NumPy 的基本概念（例如索引、矢量化、广播、(g)ufunc 和 dtype）有相当数量的内容。这可以更好地组织和阐明，以确保它确实是关于解释概念的，而不是与教程或操作方法之类的内容混合在一起。

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

一些可以扩展的概念示例：

  • 副本与视图；

  • BLAS 和其他线性代数库；

  • 花式索引。

此外，参考指南中还有许多解释，应将其移至这个新的专用解释部分。

教程#

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

教程创意（这些捕捉了有意义的内容类型，并不一定是我们建议实施的确切主题）

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

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

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

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

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

软件木匠讲师培训材料中的准备教学文档 [2]很好地总结了如何编写有效的教学计划（教程非常相似）。除了添加新的教程外，我们还建议撰写一份如何编写教程的文档，这将帮助用户为文档贡献新的高质量内容。

数据集#

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

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

实现#

目前，NumPy的文档可能令人困惑，尤其对于初学者而言。我们的建议是按照以下结构重新组织文档

  • 面向用户

    • 绝对初学者教程

    • 主要教程部分

    • NumPy常用任务的How To

    • 参考指南（API参考）

    • 解释

    • F2Py指南

    • 术语表

  • 面向开发者/贡献者

    • 贡献者指南

    • 底层文档

    • 构建和扩展文档

    • 基准测试

    • NumPy增强提案

  • 元信息

    • 报告错误

    • 发行说明

    • 关于NumPy

    • 许可证

后续想法#

除了在某种程度上重写当前文档之外，拥有一个允许社区更多贡献的技术基础设施也是理想的。例如，如果可以按原样提交Jupyter Notebook作为教程或How To，这可能会吸引更多贡献者并扩大NumPy社区。

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

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

讨论#

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

参考文献和脚注#