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 多线程，使用 multiprocessing、随机数生成等）

  • 存储和加载数据（`.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 的 Conway 生命游戏（注意：已在 Nicolas Rougier 的书中）

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

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

  • 地理空间数据（例如，使用 lat/lon/time 创建每个年份的地图，通过堆叠数组，例如 gridMet 数据）

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

来自软件 carpentry 教师培训材料的准备教学文档 [2] 是编写有效教学计划（以及教程）的不错总结。除了添加新的教程之外，我们还建议编写如何编写教程文档，这将帮助用户为文档贡献高质量内容。

数据集#

在 NumPy 文档中使用有趣的数据需要让所有用户都可以访问这些数据，要么在 NumPy 内部，要么在单独的包中。前者不是最好的主意，因为它很难做到，而不会显着增加 NumPy 的大小。

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

实现#

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

  • 对于用户

    • 绝对初学者教程

    • 主要教程部分

    • NumPy 常用任务的如何做指南

    • 参考指南（API 参考）

    • 解释

    • F2Py 指南

    • 词汇表

  • 对于开发者/贡献者

    • 贡献者指南

    • 幕后文档

    • 构建和扩展文档

    • 基准测试

    • NumPy 改进提案

  • 元信息

    • 报告 bug

    • 发行说明

    • 关于 NumPy

    • 许可证

后续想法#

除了在一定程度上重写当前文档之外，最好有一个技术基础设施，允许社区做出更多贡献。例如，如果 Jupyter Notebooks 可以按原样提交为教程或如何做指南，这可能会吸引更多贡献者，并扩大 NumPy 社区。

同样，如果人们可以下载一些以 Notebook 格式的文档，这当然意味着人们会使用更少过时的资料来学习 NumPy。

新文档结构也使得翻译更容易。

讨论#

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

参考文献和脚注#

此页面上的内容