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 网站从未得到它所需和应得的关注。我们希望并打算很快改变这种情况。本文档描述了如何设计当前网站的替代方案以更好地满足我们多元化社区需求的想法和要求。

总的来说，我们的目标是

• 现代、简洁的外观

• 易于部署的静态站点

• 易于导航的结构

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

• 可能的多种语言翻译/i18n

此网站扮演着几个角色

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

• 它应该链接到文档（现在分别托管在 https://docs.scipy.org.cn/，不久的将来将在 https://numpy.com.cn/doc 上托管）。

• 它应该解决项目的各个方面（例如，NumPy 是什么以及为什么要使用它、社区、项目组织、资金、与 NumFOCUS 和可能的其他组织的关系）

• 它应该链接到其他地方，以便每种类型的利益相关者（初级和高级用户、教育工作者、打包人员、资助者等）都能找到自己的方向

动机和范围

当前的 numpy.org 网站几乎没有内容，其设计也很糟糕。这会影响许多寻找信息的使用者。它还会影响 NumPy 项目的许多其他方面，从寻找新的贡献者到筹款。

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

详细说明

用户体验

除了 NumPy 徽标外，几乎没有什么可以或需要从当前网站保留的内容。我们将很大程度上依赖新网站的设计者提出的想法和建议。

作为参考点，我们可以使用 Jupyter 网站（这可能是我们生态系统中设计最好的网站），以及设计良好的 QuantEcon 和 Julia 网站。

网站

静态站点是必须的。有很多高质量的静态站点生成器。当前网站使用 Sphinx，但这并不是最好的选择——它很难进行主题设置，并且由于 Sphinx 的主要目标是文档，因此生成的网站文本过多。

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

1. 使用范围如何？ 在寻找维护或改进站点的帮助时，这一点非常重要。更流行的框架通常维护得也更好，因此错误或过时的可能性较小。

2. 易于部署。 大多数生成器都满足此标准，但是诸如对 GitHub Pages 的内置支持之类的功能有所帮助。

3. 实施新网站的人员的偏好。 每个人都有自己的偏好。构建新网站是一项大量的工作。因此，我们应该考虑那些正在进行这项工作的人的意见。

流量

当前网站每月接收约 500,000 名独立访客。通过重新设计的网站和相关内容，访客数量有可能达到 500-600 万——与 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 带宽。额外的带宽费用为 20 美元/100GB。他们支持全球 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 年下半年会有 1 或 2 位技术作家通过 Google Season of Docs 参与该项目。他们可能会帮助改进内容及其组织方式。

我们建议采用以下结构：

0. 首页：NumPy 的基本内容（例如，与 jupyter.org 进行比较），一个或几个关键用户案例（例如，与 julialang.org 进行比较）

1. 安装

2. 文档

3. 数组计算

4. 社区

5. 学习

6. 关于我们

7. 贡献

8. 捐赠

可能还有一些其他页面，例如关于性能的页面，这些页面链接自某个主要页面。

利益相关者内容

网站中的此类内容应尽可能少。网站上的某个位置应该链接到针对以下用户的特定内容：

• 初学者（快速入门，教程）

• 高级用户

• 教育工作者

• 打包人员

• 依赖于 NumPy 的软件包作者

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

翻译（多语言/i18n）

NumPy 在世界各地都有用户。大多数用户不是以英语为母语，许多人英语说得不好或根本不会说英语。因此，提供多种语言的内容可能会满足一个很大的未满足需求。这也有可能使 NumPy 项目更加多样化和友好。

另一方面，很少有项目拥有多语言网站是有充分理由的。这可能会增加很多额外的工作。维护人员的额外工作成本很高——他们已经难以应付工作量。因此，我们必须非常仔细地考虑多语言网站是否可行，并权衡成本和效益。

我们首先要声明：将所有文档甚至整个用户指南的翻译作为 NumPy 项目的一部分进行维护是不可行的。只需看看我们文档的篇幅以及我们更改文档的频率，就会明白这一点。但是，也许只翻译网站的顶级页面是可行的。这些页面变化不频繁，内容量有限（大约 5-10 页文本）。

我们建议为添加语言设定以下要求：

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

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

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

此外，我们建议制定一项关于何时再次取消对某种语言的支持的策略（最好是隐藏而不是删除内容）。如果该语言不再有维护人员，并且翻译覆盖率低于可接受的阈值（例如 80%），则可以这样做。

提供翻译的好处包括：

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

• 可能吸引更多文化和地域多样化的贡献者

权衡取舍是：

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

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

• 进行内容更改的成本更高，会为语言维护人员增加工作量

• 任何内容更改都应延迟足够的时间以准备好翻译

我们能否定义一个足够小的页面和内容集，以便这样做是有意义的？可能可以。

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

样式和图形设计

除了“现代、简洁的外观”目标之外，我们选择不指定太多内容。设计师可能比本提案的作者有更好的想法，因此我们将在实施阶段与设计师合作。

NumPy 的 logo 可以进行一些润色。该 logo 广为人知，其颜色和设计都很好，但外观和感觉可能有点过时了。

其他方面

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

向后兼容性

选择静态网站生成器后，我们将从 Sphinx 迁移 numpy.org（网站，*不包括文档*）。当前部署可以保留到将来决定弃用日期之前（可能基于我们对新网站的满意度）。

上面列出的所有站点生成器都可以查看生成的 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

参考文献和脚注

版权

本文件已进入公有领域。