NEP 28 — numpy.org 网站改版

作者:

Ralf Gommers <ralf.gommers@gmail.com>

作者:

Joe LaChance <joe@boldmetrics.com>

作者:

Shekhar Rajak <shekharrajak.1994@gmail.com>

状态:

最终

类型:

信息性

创建日期:

2019-07-16

决议:

https://mail.python.org/pipermail/numpy-discussion/2019-August/079889.html

摘要

NumPy 是用于 Python 数值和科学计算的基础库。它被数百万人使用，拥有一支庞大的维护者和贡献者团队。尽管如此，其 numpy.org 网站从未获得应有的关注。我们希望并打算尽快改变这一现状。本文档描述了如何设计替代当前网站的想法和要求，以更好地服务于我们多元化的社区需求。

在宏观层面，我们的目标是

• 现代、简洁的外观

• 易于部署的静态网站

• 易于导航的结构

• 满足所有类型利益相关者需求的内容

• 可能的多语言翻译 / 国际化

该网站具有以下几个作用

• 它是新用户进入项目的入口

• 它应该链接到文档（目前托管在 https://docs.scipy.org.cn/，不久的将来将托管在 https://numpy.net.cn/doc，是独立托管的）。

• 它应该涵盖项目的各个方面（例如 NumPy 是什么以及为何使用它、社区、项目组织、资金、与 NumFOCUS 以及其他可能组织的联系）

• 它应该链接到其他地方，以便所有类型的利益相关者（初级和高级用户、教育工作者、打包者、资助者等）都能找到所需信息

动机和范围

当前的 numpy.org 网站几乎没有内容，并且设计不佳。这影响了许多前来寻找信息的用户。它还影响了 NumPy 项目的许多其他方面，从寻找新的贡献者到筹款。

拟议改版范围是顶层 numpy.org 网站，该网站目前仅包含几页内容，改版后可能会有大约十页。更改文档（用户指南、参考指南和 NumPy 手册中的其他一些页面）不在此提案的范围之内。

详细描述

用户体验

除了 NumPy 标志外，当前网站几乎没有什么需要保留的内容。我们将在很大程度上依赖新网站设计师的理念和建议。

作为参考，我们可以使用 Jupyter 网站，它可能是我们生态系统中设计最好的网站，以及设计同样出色的 QuantEcon 和 Julia 网站。

网站

静态网站是必需的。有许多高质量的静态网站生成器。当前网站使用 Sphinx，但它不是最佳选择——它难以设置主题，并且由于 Sphinx 的主要目标是文档，导致网站文本过多。

选择静态网站生成器时应考虑以下因素

1. 它的使用范围有多广？ 这在寻求网站维护或改进帮助时很重要。更流行的框架通常也维护得更好，因此出现 bug 或过时的可能性更小。

2. 易于部署。 大多数生成器都符合此标准，但像对 GitHub Pages 的内置支持会有帮助。

3. 新网站实施者的偏好。 每个人都有自己的偏好。而且构建一个新网站需要大量工作。因此，我们应该考虑实施者的意见。

流量

当前网站每月约有 50 万独立访问者。通过重新设计的网站和相关内容，访问者数量有潜力达到 5-6 百万——与 scipy.org 或 matplotlib.org 相似的水平——甚至更多。

静态网站生成器的可能选项

1. Jekyll。 这是一个维护良好的选项，拥有 855 名 GitHub 贡献者，最近一个月内仍有贡献。Jekyll 用 Ruby 编写，具有简单的命令行界面 (CLI)。Jekyll 还有一个庞大的主题目录，尽管大部分需要付费。有几个合适且免费的主题（serif、uBuild、Just The Docs）。大多数主题可能都支持移动响应式设计，这应该是一个要求。Jekyll 使用 Liquid 模板和 YAML 的组合来渲染 HTML，内容以 Markdown 编写。i18n 功能并非 Jekyll 原生，但可以轻松添加。Jekyll 的一个好处是它可以由 GitHub Pages 自动运行，因此无需通过 CI 系统实现部署。

2. Hugo。 这是另一个维护良好的选项，拥有 554 名贡献者，最近一个月内仍有贡献。Hugo 用 Go 编写，与 Jekyll 类似，具有易于使用的命令行界面 (CLI) 来生成静态网站。同样，与 Jekyll 类似，Hugo 也有一个庞大的主题目录。这些主题似乎是免费的，不像 Jekyll 的一些主题。（示例着陆页主题、文档主题）。Hugo 使用 Jade 作为其模板语言，内容也以 Markdown 编写。i18n 功能是 Hugo 原生的。

3. Docusaurus。 Docusaurus 是 Facebook 开发的一款响应式静态网站生成器。与之前的选项不同，Docusaurus 不带主题，因此我们不希望将其用于我们的着陆页。这是一个用 React 编写的优秀文档选项。Docusaurus 原生支持 i18n（通过 Crowdin）、文档版本控制和文档搜索。

Jekyll 和 Hugo 都是优秀的选项，应在未来得到支持，也是 NumPy 的良好选择。Docusaurus 具有 Jekyll 和 Hugo 没有的一些额外功能，如版本控制和搜索，但可能不适合作为着陆页——尽管它以后可能是一个很好的高级文档网站选项。

部署

无需运行服务器，根据我们的经验，这样做会大量耗费维护者的时间。

1. Netlify。 Netlify 在使用 100GB 带宽之前是免费的。额外的带宽费用为每 100GB 20 美元。它们支持全球 CDN 系统，这将使其他地区用户的加载时间保持快速。Netlify 还与 GitHub 集成，方便部署。当拉取请求合并时，Netlify 会自动部署更改。DNS 设置简单，并且支持 HTTPS。

2. GitHub Pages。 GitHub Pages 也有 100GB 的带宽限制，不清楚是否可以购买额外带宽。网站部署位置也不明确，应假定网站未在全球部署。GitHub Pages 具有易于使用的 CI 和 DNS 功能，类似于 Netlify。支持 HTTPS。

3. Cloudflare。 一个优秀的选项，可能需要额外的 CI 来实现相同的部署便利性。

根据当前的流量，以上所有选项都适用于 NumPy 网站。如果需要，更新到新的部署策略所需的工作量，与开发网站本身相比微不足道。如果选择 Cloudflare 等提供商，可能需要额外的 CI（例如 CircleCI），以实现与 GitHub Pages 或 Netlify 类似的部署。

分析

维护者了解 numpy.org 的访问量是有益的。Google Analytics 提供访问者数量和地理位置信息。这将有助于更具战略性地支持和部署，并帮助维护者了解流量来源。

Google Analytics 是免费的。必须将 Google 提供的一段脚本添加到主页。

网站结构

我们旨在使新网站的第一个版本内容量较少。新页面可以稍后添加，当前更重要的是网站设计正确并发布一些基本信息。请注意，在 2019 年下半年，我们预计将通过 Google Season of Docs 项目引入 1 到 2 名技术作家。他们可能会帮助改进内容的质量和组织方式。

我们建议采用以下结构

0. 首页：NumPy 是什么的核心内容（可参考 jupyter.org），一两个关键用户案例（可参考 julialang.org）

1. 安装

2. 文档

3. 数组计算

4. 社区

5. 学习

6. 关于我们

7. 贡献

8. 捐赠

可能还有其他一些页面，例如关于性能的页面，将从主页面链接。

利益相关者内容

本站内部内容应尽可能少。在网站的某个地方，我们应该链接到特定于以下内容：

• 初级用户（快速入门，教程）

• 高级用户

• 教育工作者

• 打包者

• 依赖 NumPy 的包作者

• 资助者（治理，路线图）

翻译（多语言 / 国际化）

NumPy 用户遍布全球。这些用户大多数不是英语母语者，许多人英语不好或根本不会说英语。因此，提供多语言内容可能满足了大量未被满足的需求。这也有助于使 NumPy 项目更加多元化和受欢迎。

另一方面，很少有项目拥有多语言网站是有充分理由的。这可能意味着大量额外的工作。维护者的额外工作成本很高——他们已经很难跟上工作量了。因此，我们必须非常仔细地考虑多语言网站是否可行，并权衡成本和收益。

我们首先断言：作为 NumPy 项目的一部分，维护所有文档甚至整个用户指南的翻译是不可行的。只需看看我们的文档量和更改频率，就能明白这一点。然而，可能只翻译网站的顶层页面是可行的。这些页面不经常更改，并且内容量有限（大约 5-10 页文本）。

我们建议添加语言时应满足以下要求

• 该语言必须有专门的维护者

• 必须有一种方法来验证内容更改（例如，第二个维护者/审阅者，或免费机器翻译工具中高质量的语言支持）

• 该语言必须拥有合理规模的目标受众（由 NumPy 维护者评估）

此外，我们提出了何时再次移除对某种语言支持的政策（最好是隐藏而非删除内容）。当该语言不再有维护者，且翻译覆盖率低于可接受的阈值（例如 80%）时，可以执行此操作。

提供翻译的好处包括

• 更好地服务许多现有和潜在用户

• 可能吸引更多文化和地理背景多元化的贡献者

权衡如下

• 维护更复杂代码库的成本

• 决定是否添加新语言的成本

• 更改内容成本更高，为语言维护者带来工作量

• 任何内容更改都应有足够的延迟才能完成翻译

我们能否定义足够小的一组页面和内容，使其值得进行此项工作？可能可以。

是否有易于使用的工具来维护翻译并将其添加到网站？有待讨论——这需要调查，并且可能取决于静态网站生成器的选择。一个潜在的选项是 Crowdin，它对开源项目免费。

风格和平面设计

除了“现代、简洁的外观”这一目标外，我们选择不过多具体说明。设计师可能比本提案的作者有更好的想法，因此我们将在实施阶段与设计师合作。

NumPy 标志可能需要修饰一下。该标志广受认可，其颜色和设计都很好，但整体观感可能有点过时了。

其他方面

有一个搜索框会很好。Sphinx 文档已经有一个搜索框，但主站上的搜索框如果能提供文档、网站以及可能与 NumPy 相关的其他领域的搜索结果，将更具意义。

向后兼容性

鉴于已选择静态网站生成器，我们将把 numpy.org（网站，不包括文档）从 Sphinx 迁移出去。当前的部署可以保留，直到决定未来的废弃日期（可能基于我们新网站的舒适度）。

上面列出的所有网站生成器都可以查看生成的 HTML 和 Javascript，并且在特定项目停止维护时，可以继续进行维护。

替代方案

我们考虑的网站整体设计替代方案

1. 更新现有网站。 可以选择一个新的 Sphinx 主题。这最初可能需要最少的资源，但是，Sphinx 不具备我们正在寻找的未来功能，例如 i18n、响应式设计和简洁现代的外观。请注意，更新文档的 Sphinx 主题可能仍然是个好主意——尽管这与本 NEP 无关。

2. 创建自定义网站。 这将消耗最多的资源，并且与静态网站生成器相比，可能带来额外的好处。所有功能都可以通过投入开发时间来添加。

讨论

• 此 NEP 的拉取请求（附有大量讨论）： numpy/numpy#14032

• 关于 NEP 审查的电子邮件： https://mail.python.org/pipermail/numpy-discussion/2019-July/079856.html

• 接受此 NEP 的提案： https://mail.python.org/pipermail/numpy-discussion/2019-August/079889.html

参考文献和脚注

版权

本文档已进入公共领域。