效能共同試行專案

本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。

專案摘要

開放原始碼組織：
成效輔助工具
技術撰稿人：
arzoo14
專案名稱：
將書籍專案區域內容轉換為 Readthedocs 和 reStructuredText 格式，並設立改善圖表的延伸目標。
專案長度：
標準長度 (3 個月)

Project description

摘要：

社群網站在開放原始碼組織中扮演著重要角色，因為它能傳播社群提供的服務、他們寶貴的貢獻、技能、文件和教學課程等。因此，我的專案旨在透過轉移及更新書籍專案區域內容 (例如 DocBook 內容、REST API 文件和 pbench Markdown 內容) 為 reStructuredText 格式，以便託管在現代化的社群 readthedocs.io 網站上，進而提升所有開放原始碼貢獻者的使用便利性。這項專案也將使社群貢獻者更輕鬆地變更及擴充這類內容。另外，我們也將改善說明文件中的圖表，讓這些圖表看起來更專業。

提案：

  1. 簡介：這些資源包括以 docbook 格式呈現的 PCP 書籍、以 manpage 格式呈現的 REST API，以及以 Markdown 格式呈現的 pbench 指南。因此，該機構目前的維護人員團隊認為，他們需要的解決方案應盡可能免除維護工作，讓開發人員社群能專注於以簡單的方式維護內容。因此，根據機構目前的需求，我會在本季 Google 文件季中實現以下目標：

    1. 將文件簿內容轉換為 reStructuredText 格式，然後代管在 Readthedocs 網站上。
    2. 將 REST API 說明文件從手冊頁面轉換為開發人員友善的格式，例如 reStructuredText 格式，並在 readthedocs 網站上代管。
    3. 將 pbench Markdown 內容轉換為 reStructuredText 格式，並在 readthedocs 網站上代管。
    4. 延伸目標是改善說明文件中的圖表。

  2. 實作方式： 目前，Performance Co-Pilot 說明文件並未採用特定格式。每當說明文件內容需要變更時，就必須由受限的一組使用者進行變更。對於活躍的社群成員來說，要變更及擴充說明文件內容並不容易。

我會借助 reStructuredText 格式、閱讀文件 (RTD) 和 Sphinx，協助機構在這次 GSoD 期間克服上述限制。

Read the Docs (RTD) 可自動建構、版本管理及代管說明文件，簡化軟體說明文件。這是 Sphinx 產生說明文件的代管平台。它結合了 Sphinx 的強大功能，並新增版本控制、全文搜尋和其他實用功能。從 Git、Mercurial 或 Subversion 提取程式碼和文件檔案，然後建構及託管說明文件。我們會在專案中使用 GitHub，因為這是存取程式碼最常用的系統。

首先，我們會建立 Read the Docs 帳戶，並連結 GitHub 帳戶。接著，我們會選取要建立說明文件的 GitHub 存放區，這時就會發生神奇的事情。

Read the Docs 會： - 複製我們的存放區。- 向我們的主分支版本製作 HTML、PDF 和 ePub 版本的文件。 - 為說明文件建立索引，允許全文搜尋功能。 - 從存放區中的每個標記和分支版本建立版本物件，讓我們視需要代管這些版本。- 在我們的存放區中啟用 webhook，這樣當我們將程式碼推送至任何分支時，就會重新建構說明文件。

Sphinx 是權威說明文件產生器，提供許多優異功能，可用於撰寫技術說明文件，包括： - 從相同來源產生網頁、可列印的 PDF、電子書閱讀器 (ePub) 專用的文件等。- 我們可以使用 reStructuredText 編寫說明文件。- 交叉參照程式碼和說明文件的完整系統。- 語法醒目顯示的程式碼範例。- 第一方和第三方擴充功能的活絡生態系統。

我會先將兩本以 docbook 格式呈現的 PCP 書籍轉換為 rst 格式，接著將 REST API 說明文件從 man 頁面格式轉換為 rst 格式，然後將 pbench Markdown 內容轉換為 rst 格式，最後將所有內容代管在 readthedocs 網站上。延伸目標就是改善說明文件中的圖表。

2.1. 轉換為 reStructuredText 格式： 第一步是將說明文件內容轉換為 reStructuredText 格式。每個章節都會有個別的 rst 檔案，只包含該章節的內容。舉例來說，「高效能共同前測使用者」和「管理員指南」一書包含八個章節。也就是說，系統會產生八個不同的 rst 檔案，對應至八個章節。rst 檔案的名稱會與章節名稱相同，以免日後造成混淆。三個 rst 檔案中會列出圖表、表格和示例清單。系統會以目前的形式，為 rst 內容全面加入超連結。同樣適用於 REST API 說明文件和 pbench 內容。所有必要事項 (例如粗體、斜體、底線、項目符號、表格、字型大小、程式碼樣式、圖片大小、對齊方式等) 都會處理完畢，並將內容轉換為 Rrt 格式。

2.2. 將 rst 與 Sphinx 整合：

ReadtheDocs 會預設使用 Sphinx 和 reStructuredText (rst)。由於我的系統中預先安裝了 Sphinx，因此我會先在專案中建立一個目錄 (命名為 Performance Co-Pilot 說明文件)，用來儲存說明文件： $ cd /path/to/project $ mkdir docs

接著，在該資料夾中執行 sphinx-quickstart： $ cd docs $ sphinx-quickstart

本快速入門會逐步說明如何建立必要的設定；在大多數情況下，我們可以直接接受預設值 (但在必要時，我們可以在設定檔中進行必要變更)。完成後，我們會提供 index.rst、conf.py 和一些其他檔案。 在 index.rst 中，我會新增 Performance Co-Pilot 的所有必要詳細資料，並為書籍、REST API 說明文件和 pbench 指南建立標題。使用者點選任何標題時，系統就會開啟該標題下的所有說明文件。

注意：索引頁面的設計會徵得導師和社群成員的同意，並視需求和規定進行變更。

index.rst 會在說明文件輸出目錄 (通常為 _build/html/index.html) 中建構為 index.html。在公開存放區中建立 Sphinx 說明文件後，我們就可以開始使用 Read the Docs，並匯入說明文件。

當我們在文件中新增任何 .rst 檔案時，系統會根據該檔案產生其他三個檔案，一個位於 doctrees 資料夾中，副檔名為 .doctree；第二個位於 Html 資料夾中，副檔名為 .html；第三個位於 html/_sources 資料夾中，副檔名為 .rst.txt。

  1. 說明文件代管：在網路上代管說明文件包含兩個步驟：匯入說明文件：首先，我會將 Read The Docs 帳戶連結至 GitHub，並匯入說明文件專案來進行建構。2. 建構說明文件：完成匯入程序的幾秒內，系統會自動從我們的公開存放區擷取程式碼，並建立相關說明文件。

  2. 網頁連結：Read the Docs 用來偵測文件和版本變更的主要方法，就是使用網頁連結。Webhook 是透過 GitHub 等存放區供應商設定，而且每次對存放區做出修訂、合併或其他變更時，系統都會通知讀取文件。收到 Webhook 通知時，我們會判斷變更是否與專案的有效版本相關，如果存在，就會觸發該版本的建構。

如此一來，所有管理員 (管理員、導師、社群貢獻者) 都能變更、延長或維護社群文件，沒有特定限制的使用者可以編輯文件中應加入的內容，或是應從說明文件中移除的內容。

  1. 主題：主題、版面配置、設計，以及其他 HTML 功能 (例如搜尋) 都會根據社群需求和規範進行調整。在社群連結期間，我會與社群成員討論這些問題。
  1. 延伸目標： 我會改善說明文件中的圖表，這是延伸目標。目前，圖表多半是簡單的黑白繪圖。我會為圖片加入更多色彩、陰影、縮放、一致性，並讓圖片看起來更整齊 / 更專業。

為達到這個目的，我會使用 draw.io (或獲得導師同意的任何其他工具)。

為了進行概念驗證，我使用 draw.io 改善了說明文件中的其中一個圖表。請參閱以下連結：https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

概念證明

我已將 PCP 書籍的一小部分 (docbook 格式) 轉換成 rst 格式，並在 readthedocs 網站上代管。請按這裡查看。

網站：https://pcp-books.readthedocs.io/en/latest/ 程式碼：https://github.com/arzoo14/PCP_Books_Demo

我也已在程式碼存放區中設定 webhook，這樣一來，程式碼存放區中的變更就會反映在網站上。

時間表和可交付成果

社群連結期 [2020 年 8 月 17 日至 9 月 13 日 ]

我會花一些時間自我熟悉社群、詳閱說明文件，並與導師討論許多事情，確保過程中不會有任何負面決定。在這段期間，我會與導師和社群成員討論主題、版面配置、設計，以及搜尋、導覽列等其他功能。在社群連結期間，我們會討論專案名稱，以及是否要建立一個網站來收錄所有三個主題，或是三個不同網站來對應三個主題。

開發文件 (2020 年 9 月 14 日至 11 月 30 日)

***2020 年 9 月 14 日至 2020 年 9 月 20 日 [第 1 週] 將「使用者和管理員指南」書籍的前四章的 DocBook 內容轉換為 rst 格式。

***2020 年 9 月 21 日至 2020 年 9 月 27 日 [第 2 週] 將 DocBook 內容轉換為 RSX 格式，以便為「使用者和管理員指南」手冊的後四章轉換內容。

***2020 年 9 月 28 日至 10 月 4 日 [第 3 週] 將「程式設計師指南」書籍的所有四個章節的 DocBook 內容轉換為 rst 格式。

***從 2020 年 10 月 5 日到 2020 年 10 月 11 日 [WEEK 4] - 在 Readthedocs 網站上代管這兩本 PCP 書籍。 - 將 REST API 說明文件從手冊頁面轉換為 rst 格式。主要到達網頁會在這段期間進行測試。- 過去三週和本週的 GSoD 專案部落格文章。

***2020 年 10 月 12 日至 10 月 18 日 [第 5 週] 將可調整時間序列索引轉換為 rst 格式。可擴充的時間序列索引涵蓋以下項目：GET /series/query、GET /series/values、GET /series/descs、GET /series/labels、GET /series/metrics、GET /series/sources、GET /series/instances、GET /series/load

***從 2020 年 10 月 19 日到 2020 年 10 月 25 日 [WEEK 6] 將 PMAPI 主機服務轉換為 rst 格式。PMAPI 主機服務索引涵蓋下列項目： GET /pmapi/context、GET /pmapi/metric、GET /pmapi/fetch 、 GET /pmapi/children GET /pmapi/indom、GET /pmapi/profile 、GET /pmapi/store 、GET /pmapi/derive GET /pmapi/metrics

***2020 年 10 月 26 日至 2020 年 11 月 1 日 [第 7 週] - 如果上週還有任何未完成的內容，我們會優先處理這些內容。 - 在 readthedocs 網站上代管 REST API 說明文件。- 過去兩週和本週的 GSoD 專案部落格文章。

***從 2020 年 11 月 2 日到 2020 年 11 月 8 日 [WEEK 8] 將 Markdown 內容轉換為 pbench 指南的 rst 格式。

***2020 年 11 月 9 日至 2020 年 11 月 15 日 [第 9 週] - 繼續將 Markdown 內容轉換為 pbench 指南的 rst 格式。 - 在 Readthedocs 網站上代管 pbench 指南 - 上週和本週的 GSoD 專案部落格文章。

***從 2020 年 11 月 16 日到 2020 年 11 月 22 日 [WEEK 10] - 在索引頁面中實作搜尋功能，方便使用者搜尋網站上其名稱的內容。 - 伸展目標開始。

***從 2020 年 11 月 23 日到 2020 年 11 月 30 日 [WEEK 11] - 改善說明文件中的所有圖表。 - 上週和本週的最終部落格 (關於我的 GSoD 專案)。- 檢查程式碼庫是否符合程式碼標準。如果不正確，請變更為標準。

專案結案期 [2020 年 11 月 30 日至 12 月 5 日 ]

  • Pencil 停機時間。我正在處理最終提交內容，確保一切正常。
  • 提交專案報告，也就是最終工作成果。
  • 提交評估結果，評估專案成效，以及與導師合作的經驗。