效能共同試行專案

本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。

專案摘要

開放原始碼機構：
效能共同測試
技術文件撰寫者：
arzoo14
專案名稱：
將書籍專案內容轉換為 Readdocs 和 reStructuredText 格式，並達成圖表改善目標的延伸目標。
專案長度：
標準長度 (3 個月)

Project description

策略：

社群網站在開放原始碼組織中扮演著重要角色，因為它傳遞了社群提供的優惠、寶貴的貢獻、技能、說明文件、教學課程等項目。因此，我的專案將目標為提高所有開放原始碼貢獻者的可用性和便利性，例如將代管的書籍專案領域內容 (例如結構化文件內容、REST API 文件和 pbench 等新型內容文件) 轉換成 docio 社群網站。這項專案能讓社群貢獻者更輕鬆地變更及擴充這項內容，進而造福更多社群。此外，做為延伸目標，說明文件中的圖表會經過改善，使其更加專業。

提案：

  1. 簡介： Performance Co-Pilot 說明文件目前有多種格式，包括 docbook 格式的 PCP 書籍、手冊格式的 REST API，以及 Markdown 格式的 pbench 指南。因此，該機構目前的維護人員團隊發現他們需要能盡量避免維護的解決方案，並讓開發人員社群完全專注於維護以簡單快速的方式維護內容。 因此，我根據機構的目前需求，在本 Google 系列文件中達成下列目標：

    1. 將教科書內容轉換為 reStructuredText 格式，並交由閱讀文件網站代管。
    2. 將 REST API 說明文件從手冊轉換為適合開發人員的格式 (例如 reStructuredText 格式，並交由 Readthedocs 網站代管)。
    3. 將 pbench MarkDown 內容轉換成 reStructuredText 格式，並代管在 Readthedocs 網站上。
    4. 延展目標則是改善說明文件中的圖表。

  2. 導入： 目前效能 Co-Pilot 說明文件並非以特定格式顯示，只要文件內容需要變更，就會需要一群設有限制的使用者進行變更。活躍的社群成員可能不太容易變更和擴充說明文件內容。

我將透過 reStructuredText 格式、閱讀文件 (RTD) 和 Sphinx，讓機構在 GSoD 期間克服這些限制。

閱讀 Google 文件 (RTD) 可自動建立文件、版本管理和代管文件，藉此簡化軟體說明文件。它是用來託管 Sphinx 產生文件的代管平台。這款處理器採用 Sphinx 的強大功能，並加入版本管控、全文搜尋和其他實用功能。這個外掛程式能從 Git、Mercurial 或 Subversion 提取程式碼和文件檔案，然後建構並代管我們的說明文件。我們會在專案中使用 GitHub，因為這是存取程式碼最常使用的系統。

如要開始使用，請先建立「閱讀文件」帳戶，並連結 GitHub 帳戶。然後選擇要建構文件的 GitHub 存放區，此時就能派上用場。

閱讀說明文件： - 複製存放區。 - 使用我們主要分支版本，建立文件的 HTML、PDF 和 EPUB 版本。 - 將說明文件編入索引，以便提供全文搜尋功能。 - 利用存放區中的每個標記和分支版本建立版本物件，以便我們一併代管這些物件。 - 在我們存放區上啟用 Webhook，將程式碼推送至任何分支版本時，系統就會重新建立說明文件。

Sphinx 是具有公信力的文件產生器，擁有許多實用的技術說明文件撰寫功能，包括： - 產生網頁、可列印的 PDF、電子閱讀器文件 (ePub) 等所有功能，都是從同一來源取得。- 可以使用 reStructuredText 來撰寫說明文件。 - 廣泛參照程式碼和說明文件的廣泛系統。 - 醒目顯示語法的程式碼範例。- 匯集第一方和第三方擴充功能的蓬勃發展生態系統。

首先，我會依序將 REST API 說明文件從手冊格式轉換成 rst 格式，再將 pbench Markdown 內容轉換成 rst 格式，最後在 Readdocs 網站上存放這兩本 PCP 格式的書籍。延展目標則是改善說明文件中的圖表。

2.1. 轉換為 reStructuredText 格式： 第一步是將說明文件內容轉換為 reStructuredText 格式。每個章節都有獨立的 RTT 檔案，內含該章節的內容。舉例來說，《效能 Co-Pilot 使用者和管理員指南》的書籍包含八個章節，這代表會有八個不同的 RSt 檔案，分別與這八個章節對應。rt 檔案名稱會與章節名稱相同，以免日後造成混淆。圖表、表格和範例清單皆位於三個不同的 RSt 檔案中。各個 RSS 內容會以目前的超連結方式完成超連結。REST API 說明文件和 pbench 內容也使用相同內容。內容轉換為文字格式時，系統會處理所有必要項目，例如粗體、斜體、底線、項目符號、表格、字型大小、程式碼樣式、圖片大小、對齊方式等。

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 文件匯入公開存放區後，即可開始透過匯入文件來使用「閱讀文件」。

如果我們在文件中新增任何 .rst 檔案，則對應該檔案，會產生三個其他檔案：一個副檔名為 .doctrees 的 doctrees 資料夾、第二個副檔名為 .html 的 Html 資料夾，另一個在副檔名為 .rst.txt 的 html/_sources 資料夾中。

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

  2. 網路攝影機： 「閱讀 Google 文件」用來偵測說明文件和版本的主要方法是透過 Webhook。Webhook 是透過我們的存放區供應商 (例如 GitHub) 設定，而且每次對存放區做出修訂版本、合併或變更時，都會收到「讀取文件」通知。收到 Webhook 通知時，我們會判斷變更是否與專案的有效版本有關；如果相符，版本就會觸發版本。

如此一來，任何人 (管理員、導師、社群貢獻者) 都可以變更、擴充或維護社群文件，不需要特定受限的使用者負責處理文件內應新增或應移除的內容。

  1. 主題： 主題、版面配置、設計和其他 HTML 功能 (例如搜尋) 會根據社群的需求和指南提供。在社區交流期間，我會和社群成員討論。
  1. 強化目標： 做為延伸目標，我會改善說明文件中的圖表。目前，圖表幾乎都是簡單的黑白繪圖。我會為圖片增添色彩、陰影、縮放、一致性，以及一般的動畫 / 更專業感。

為達成這個目的，我使用 draw.io (或經輔導者同意的其他工具)。

為提供概念驗證，我根據 draw.io 改善說明文件中的一張圖表文件連結如下：https://docs.google.com/document/d/1CUukNgwh6PvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

同意證明

我已將一小部分的 PCP 書籍 (docbook 格式) 轉換成 rst 格式，並且由閱讀文件網站代管。請前往這裡查看。

網站 - 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 日 [WEEK 1] 《使用者與管理員指南》手冊的前四章將教科書內容轉換成 rst 格式。

***2020 年 9 月 21 日至 2020 年 9 月 27 日 [WEEK 2] 《使用者與管理員指南》後續四章將教科書內容轉換成 rt 格式。

***2020 年 9 月 28 日至 2020 年 10 月 4 日 [WEEK 3] 《程式設計人員指南》這 4 個章節均將教科書內容轉換成 rt 格式。

***2020 年 10 月 5 日至 2020 年 10 月 11 日 [第 4 週] - 在 Readdocs 網站上代管兩本 PCP 書籍。 - 將 REST API 說明文件從手冊格式轉換成 rst 格式。這段期間內，主要到達網頁將進行說明。 - 在過去三週和當週建立 GSoD 專案的網誌。

***2020 年 10 月 12 日至 2020 年 10 月 18 日 [WEEK 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 Host Services 索引涵蓋下列項目： 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/derive GET /pmapi/derive

***2020 年 10 月 26 日至 2020 年 11 月 1 日 [WEEK 7] - 如未在最後幾週保留任何商品，我們會優先提供。 - Readthedocs 網站提供 REST API 說明文件。 - 我的 GSoD 專案 (即我的 GSoD 專案) 過去兩週和當週。

***2020 年 11 月 2 日至 2020 年 11 月 8 日 [WEEK 8] 將 Markdown 內容轉換成 pbench 指南專用的 rst 格式。

***2020 年 11 月 9 日至 2020 年 11 月 15 日 [WEEK 9] - 繼續將 Markdown 內容轉換成 PST 指南的 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 日 ]

  • 鉛筆休息時間正在處理最終提交內容，並確保一切正常。
  • 提交專案報告，也稱為最終工作產品。
  • 要求評估專案表現以及與導師的工作經驗。