Ctrl+K

NEP 44 — 重构 NumPy 文档#

作者：

拉尔夫·戈默斯

作者：

梅丽莎·门多萨

作者：

火星李

地位：

公认

类型：

过程

创建：

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)ufuncs 和 dtypes）的内容数量合理。这可以更好地组织和澄清，以确保它真正是为了解释概念，而不是与教程或如何喜欢的内容混合在一起。

除了基本的 NumPy 概念之外，几乎没有任何解释。

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

  • 副本与视图；

  • BLAS 和其他线性代数库；

  • 花哨的索引。

此外，《参考指南》中有很多解释，应移至这个新的专用解释部分。

教程

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

教程的想法（这些捕获了有意义的事物类型，它们不一定是我们建议实现的确切主题）：

  • 仅使用 NumPy 进行康威的生命游戏（注：已经在Nicolas Rougier 的书中）

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

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

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

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

Software Carpentry Instructor Training 材料中的准备教学文档[ 2 ]很好地总结了如何编写有效的课程计划（教程也非常相似）。除了添加新的教程之外，我们还提出了如何编写教程文档，这将帮助用户为文档贡献新的高质量内容。

数据集#

使用 NumPy 文档中的有趣数据需要让所有用户能够访问该数据，无论是在 NumPy 内部还是在单独的包中。前者不是最好的想法，因为如果不显着增加 NumPy 的大小就很难做到。即使对于 SciPy 来说，迄今为止也没有达成共识（请参阅 scipy PR 8707关于添加新 scipy.datasets子包）。

所以我们的目标是一个新的（纯Python）包，命名为numpy-datasets或 scipy-datasets或类似的东西。该包可以从 scikit-learn 传输数据集的方式中吸取一些教训。小数据集可以包含在存储库中，大数据集可以通过下载器类或函数访问。

执行＃

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

  • 对于用户：

    • 绝对初学者教程

    • 主要教程部分

    • 如何使用 NumPy 执行常见任务

    • 参考指南（API参考）

    • 说明

    • F2Py 指南

    • 词汇表

  • 对于开发者/贡献者：

    • 贡献者指南

    • 幕后文档

    • 构建和扩展文档

    • 标杆管理

    • NumPy 增强提案

  • 元信息

    • 报告错误

    • 发行说明

    • 关于 NumPy

    • 执照

后续想法#

除了在某种程度上重写当前文档之外，理想的情况是拥有一个允许社区做出更多贡献的技术基础设施。例如，如果 Jupyter Notebooks 可以作为教程或操作方法按原样提交，这可能会创造更多的贡献者并扩大 NumPy 社区。

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

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

讨论＃

围绕此 NEP 的讨论可以在 NumPy 邮件列表中找到：

参考文献和脚注#

在本页