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.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 编写。国际化功能不是 Jekyll 的原生功能，但可以轻松添加。Jekyll 的一个好处是它可以由 GitHub Pages 自动运行，因此无需实施通过 CI 系统的部署。

  2. Hugo。 这是另一个维护良好的选项，拥有 554 个贡献者，并在上个月有贡献。Hugo 是用 Go 编写的，与 Jekyll 类似，它具有简单的 CLI 接口来生成静态网站。同样，与 Jekyll 类似，Hugo 拥有大量的 主题 目录。这些主题似乎是免费的，与 Jekyll 的某些主题不同。（示例登陆页面主题、文档主题）。Hugo 使用 Jade 作为其模板语言，内容也使用 Markdown 编写。国际化功能是 Hugo 的原生功能。

  3. Docusaurus。 Docusaurus 是由 Facebook 制作的响应式静态网站生成器。与之前的选项不同，Docusaurus 没有提供主题，因此我们不希望将其用于我们的登陆页面。这是一个用 React 编写的出色的文档选项。Docusaurus 原生支持国际化（通过 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 才能获得与 GitHub Pages 或 Netlify 相似的部署体验。

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

分析#

对于维护人员来说，了解有多少访客访问 numpy.org 非常有益。Google Analytics 提供访客数量和位置。这将有助于更具策略性地支持和部署，并帮助维护人员了解流量来自哪里。

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

网站结构#

我们的目标是将新网站的第一个版本的内容数量保持在较小范围内。新页面可以在以后添加，现在更重要的是要将网站设计做好，并发布一些基本信息。请注意，我们预计在 2019 年下半年通过 Google Season of Docs 聘请 1 或 2 名技术作家参与项目。他们可能会帮助改进内容及其组织方式。

我们建议以下结构

  1. 首页：NumPy 的基本要素（与 jupyter.org 相比）、一个或两个关键用户案例（与 julialang.org 相比）

  2. 安装

  3. 文档

  4. 数组计算

  5. 社区

  6. 学习

  7. 关于我们

  8. 贡献

  9. 捐赠

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

利益相关者内容#

这应该尽可能少地在网站内包含内容。我们应该在网站上的某个地方链接到针对以下方面的内容

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

  • 高级用户

  • 教育工作者

  • 打包人员

  • 依赖 NumPy 的软件包作者

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

翻译（多种语言 / 国际化）#

NumPy 在世界各地拥有用户。大多数用户不是英语母语使用者，许多用户不会说英语，或者英语水平很差。因此，提供多种语言的内容可能可以满足巨大的未满足需求。它也有可能帮助使 NumPy 项目更加多元化和友好。

另一方面，有充分的理由说明为什么很少有项目拥有多语言网站。这可能需要大量额外的工作。维护人员的额外工作成本很高 - 他们已经难以应付工作量。因此，我们必须非常谨慎地考虑多语言网站是否可行，并权衡成本和收益。

我们首先断言：维护所有文档的翻译，甚至整个用户指南，作为 NumPy 项目的一部分，是不可行的。我们只需要看看我们文档的量以及我们更改它的频率，就可以意识到事实的确如此。不过，可能只翻译网站的顶层页面是可行的。这些页面更改频率很低，并且内容量有限（大约 5-10 页文字）。

我们建议添加语言的以下要求

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

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

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

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

拥有翻译的好处包括

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

  • 有可能吸引更多样化的文化和地理分布的贡献者

权衡取舍是

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

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

  • 进行内容更改的成本更高，为语言维护者创造工作

  • 任何内容更改都应延迟足够长的时间，以便翻译到位

我们能否定义一小部分页面和内容，使其有意义？ 当然可以。

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

样式和图形设计#

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

NumPy 徽标可以进行一些修饰。该徽标广为人知，其颜色和设计也很好，但是整体感觉可能有点过时了。

其他方面#

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

向后兼容性#

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

上面列出的所有站点生成器都具有对生成的 HTML 和 Javascript 的可见性，并且可以继续维护，即使某个项目不再维护。

替代方案#

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

  1. 更新当前站点。 可以选择新的 Sphinx 主题。这最初可能需要最少的资源，但是 Sphinx 不具备我们将来想要的功能，例如 i18n、响应式设计和简洁、现代的外观。请注意，更新文档的 Sphinx 主题可能仍然是一个好主意 - 虽然它与本 NEP 正交。

  2. 创建自定义站点。 这将需要最多的资源，并且与静态网站生成器相比，可能具有额外的好处。所有功能都可以在开发人员时间成本内添加。

讨论#

参考文献和脚注#

本页内容