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)ufuncs 和 dtypes）的内容相当多。这些内容可以更好地组织和阐明，以确保它们真正关于解释概念，而不是与教程或操作指南类内容混合在一起。

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

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

  • 复制与视图；

  • BLAS 和其他线性代数库；

  • 花式索引。

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

教程#

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

教程想法（这些想法捕捉到有意义的内容类型，不一定是我们建议实现的具体主题）

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

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

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

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

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

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

数据集#

在 NumPy 文档中使用有趣的数据需要让所有用户都能访问这些数据，无论是在 NumPy 内部还是在单独的包中。前者并不是最好的主意，因为它很难实现，而且会显著增加 NumPy 的大小。

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

实现#

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

  • 针对用户

    • 绝对初学者教程

    • 主要教程部分

    • 使用 NumPy 完成常见任务的 How Tos

    • 参考指南（API 参考）

    • 解释

    • F2Py 指南

    • 术语表

  • 针对开发者/贡献者

    • 贡献者指南

    • 内部文档

    • 构建和扩展文档

    • 基准测试

    • NumPy 增强提案

  • 元信息

    • 报告错误

    • 发行说明

    • 关于 NumPy

    • 许可证

后续想法#

除了在一定程度上重写当前文档外，理想情况下应该有一个技术基础设施，允许社区更多地参与贡献。例如，如果可以将 Jupyter 笔记本原样提交为教程或 How-Tos，这可能会吸引更多贡献者并扩大 NumPy 社区。

类似地，如果人们可以以笔记本格式下载一些文档，这肯定意味着人们在学习 NumPy 时会使用较少的过时材料。

如果新的文档结构可以更容易地进行翻译，那也很有意思。

讨论#

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

参考文献和脚注#

本页内容