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://scipy-docs.dev.org.tw/ 上，並在不久的將來託管在 https://numpy.dev.org.tw/doc 上)。

• 它應涵蓋專案的各個方面 (例如 NumPy 是什麼以及您為何要使用它、社群、專案組織、資金、與 NumFOCUS 以及可能與其他組織的關係)

• 它應連結到其他地方，以便每種類型的利害關係人 (初學者和進階使用者、教育工作者、封裝者、資助者等) 都能找到他們的路徑

動機和範圍

目前的 numpy.org 網站幾乎沒有內容，且其設計很差。這影響了許多來此尋找資訊的使用者。它也影響了 NumPy 專案的許多其他方面，從尋找新的貢獻者到募款。

提議重新設計的範圍是頂層 numpy.org 網站，該網站目前僅包含幾個頁面，並且在重新設計後可能包含大約十個頁面。變更文件 (使用者指南、參考指南以及 NumPy 手冊中的一些其他頁面) 不在此提案的範圍內。

詳細描述

使用者體驗

除了 NumPy 標誌外，目前網站幾乎沒有什麼可以或需要保留的。我們將很大程度上依賴新網站設計師的想法和提案。

作為參考點，我們可以參考 Jupyter 網站，它可能是我們生態系統中設計最好的網站，以及 QuantEcon 和 Julia 網站，它們的設計也很好。

網站

靜態網站是必須的。有許多高品質的靜態網站產生器。目前的網站使用 Sphinx，但這不是最佳選擇 - 它很難設定主題，並且由於 Sphinx 的主要目標是文件，因此導致網站文字過於繁重。

選擇靜態網站產生器時應考慮以下事項

1. 它的使用廣泛程度如何？ 這在尋求協助維護或改進網站時很重要。更流行的框架通常也維護得更好，因此錯誤或過時的可能性更小。

2. 易於部署。 大多數產生器都符合此標準，但是像內建支援 GitHub Pages 之類的功能會有所幫助。

3. 實作新網站的人的偏好。 每個人都有自己的偏好。而且建置新網站需要大量工作。因此，我們應將從事工作的人的意見納入考量。

流量

目前的網站每月接收約 500,000 名不重複訪客。透過重新設計的網站和相關內容，訪客人數有可能達到 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。 在使用 100GB 頻寬之前，使用 netlify 是免費的。額外頻寬費用為 $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 年下半年，我們期望透過 Google Season of Docs 讓 1 或 2 位技術寫作者參與專案。他們可能會協助改進內容和內容組織。

我們建議以下結構

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 主題。這最初可能需要最少的資源，但是，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

參考文獻和註腳

版權

本文檔已被置於公共領域。