NEP 28 — numpy.org 网站重新设计

作者：

拉尔夫·戈默斯 <拉尔夫.戈默斯@gmail 。​ com >

作者：

乔·拉查斯 <乔@boldmetrics。com >

作者：

谢卡尔·拉贾克 <谢卡尔·拉贾克. 1994 @ gmail 。 com >

地位：

最终的

类型：

信息性

创建：

2019-07-16

解决：

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

抽象的

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

从高层次来看，我们的目标是：

• 现代、干净的外观

• 易于部署的静态站点

• 易于导航的结构

• 涉及所有类型利益相关者的内容

• 可能的多语言翻译 / i18n

该网站有几个作用：

• 这是新用户进入项目的入口点

• 它应该链接到文档（该文档单独托管，现在在 http://docs.scipy.org/上，不久的将来在http://numpy.org/doc上）。

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

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

动机和范围

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

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

详细说明

用户体验

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

作为参考点，我们可以使用Jupyter 网站，它可能是我们生态系统中设计最好的网站，还有 QuantEcon和Julia 网站，它们也设计得很好。

网站

静态站点是必须的。有许多高质量的静态站点生成器。当前的网站使用 Sphinx，但这不是最佳选择 - 由于 Sphinx 的主要目标是文档，因此很难主题化并导致网站文本过多。

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

1. 它的使用有多广泛？当寻求维护或改进网站的帮助时，这一点很重要。更流行的框架通常也得到更好的维护，因此出现错误或过时的可能性较小。

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

3. 新网站实施者的偏好。每个人都有自己的喜好。建立一个新网站需要大量的工作。因此，我们应该考虑那些从事这项工作的人的意见。

交通

目前的网站每月接收大约 500,000 名独立访问者。通过重新设计的网站和相关内容，访问者数量有可能达到 5-600 万（与 scipy.org或matplotlib.org类似的水平）或更多。

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

1. 杰基尔。这是一个维护良好的选项，有 855 名 Github 贡献者，在上个月内做出了贡献。 Jekyll 用 Ruby 编写，并具有简单的 CLI 界面。 Jekyll 也有一个很大的主题目录 ，尽管大多数都需要花钱。有几个合适且免费的主题（ serif、 uBuild、 Just The Docs ）。大多数主题可能都适合移动设备，这应该是一个要求。 Jekyll 使用 Liquid 模板和 YAML 的组合来渲染 HTML，内容以 Markdown 编写。 i18n 功能不是 Jekyll 原生的，但可以轻松添加。 Jekyll 的一大好处是它可以由 GitHub Pages 自动运行，因此不需要通过 CI 系统进行部署。

2. 雨果.这是另一个维护良好的选项，有 554 名贡献者，在上个月内做出了贡献。 Hugo是用Go编写的，与Jekyll类似，有一个简单易用的CLI界面来生成静态站点。同样，与 Jekyll 类似，Hugo 有一个很大的 主题目录。与 Jekyll 的某些主题不同，这些主题似乎是免费的。 （示例登陆页面主题、 文档主题）。 Hugo 使用 Jade 作为模板语言，内容也是用 Markdown 编写的。 i18n 功能是 Hugo 原生的。

3. 多库龙。 Docusaurus 是 Facebook 制作的响应式静态网站生成器。与之前的选项不同，Docusaurus 没有主题，因此我们不想将其用于我们的登陆页面。这是一个用 React 编写的优秀文档选项。 Docusaurus 本身支持 i18n（通过 Crowdin）、文档版本控制和文档搜索。

Jekyll 和 Hugo 都是优秀的选择，未来应该得到支持，并且对于 NumPy 来说也是不错的选择。 Docusaurus 有几个额外的功能，例如 Jekyll 和 Hugo 没有的版本控制和搜索，但可能不太适合作为登陆页面 - 不过，对于以后的高级文档网站来说，它可能是一个不错的选择。

部署

不需要运行服务器，根据我们的经验，这样做会极大地消耗维护人员的时间。

1. 网络化。在使用 100GB 带宽之前，netlify 是免费的。额外带宽费用为 20 美元/100GB。他们支持全球 CDN 系统，这将为其他地区的用户提供快速的加载时间。 Netlify 还集成了 Github，可以轻松部署。合并拉取请求时，Netlify 将自动部署更改。 DNS很简单，还支持HTTPS。

2. Github 页面。 Github Pages 也有 100GB 的带宽限制，目前尚不清楚是否可以购买额外的带宽。还不清楚站点部署在哪里，并且应该假设站点没有部署在全球范围内。 Github Pages 有一个易于使用的 CI 和 DNS，类似于 Netlify。支持 HTTPS。

3. 云耀。这是一个很好的选择，可能需要额外的 CI 才能实现同样的轻松部署。

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

分析

对于维护人员来说，了解有多少访问者访问 numpy.org 是有益的。 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 徽标需要修饰一下。该标志被广泛认可，其颜色和设计都很好，但外观和感觉可能有点过时。

其他方面

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

向后兼容性

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

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

备择方案

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

1. 更新当前站点。可以选择新的狮身人面像主题。这最初可能会占用最少的资源，但是，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

参考文献和脚注

版权所有

本文档已置于公共领域。