效果联合试行项目

本页详细介绍了 Google 文档季收录的技术文案项目。

项目摘要

开源组织：
性能辅助驾驶员
技术文档工程师：
arzoo14
项目名称：
将图书项目领域内容转换为 readthedocs 和 reStructuredText 格式，并设定了改进图表的延伸目标。
项目时长：
标准时长（3 个月）

Project description

摘要：

社区网站在开源组织中发挥着重要作用，因为它可以传播社区提供的产品理念、宝贵贡献、技能、文档和教程等。因此，我的项目旨在通过将图书项目领域内容（即 docbook 内容、REST API 文档和 pbench Markdown 内容）转换和更新为 reStructuredText 格式，以便在现代社区网站 readthedocs.io 上托管这些内容，从而提高所有开源贡献者的易用性和便捷性。该项目还将让社区贡献者受益，因为他们可以更轻松地更改和扩展这些内容。此外，作为一个远期目标，我们还将改进文档中的图表，使其看起来更专业。

提案：

  1. 概览：目前，效果助手文档有几种不同的格式。这些文档包括采用 Docbook 格式的 PCP 图书、采用手册格式的 REST API 和采用 Markdown 格式的 pbench 指南。因此，该组织的现有维护者团队认为，他们需要一个尽可能无需维护的解决方案，让开发者社区能够完全专注于以简化且轻松的方式维护其内容。 因此，根据本组织当前的需求，我将在本 Google 文档发布季实现以下目标：

    1. 将 docbook 内容转换为 reStructuredText 格式，并托管在 readthedocs 网站上。
    2. 将 REST API 文档从手册页格式转换为适合开发者的格式（即 reStructuredText 格式），并将其托管在 readthedocs 网站上。
    3. 将 pbench MarkDown 内容转换为 reStructuredText 格式，并托管在 readthedocs 网站上。
    4. 远大目标是改进文档中的图表。

  2. 实现方式：目前，效果助手文档没有采用特定格式。每当需要更改文档内容时，都需要由一组受限用户进行更改。对于活跃的社区成员来说，更改和扩展文档内容并非易事。

在本次 GSoD 中，我将帮助该组织借助 reStructuredText 格式、Read the Docs (RTD) 和 Sphinx 克服这些限制。

Read the Docs (RTD) 可自动为我们构建、版本控制和托管文档，从而简化软件文档的管理。它是 Sphinx 生成的文档的托管平台。它采用了 Sphinx 的强大功能，并添加了版本控制、全文搜索和其他实用功能。它会从 Git、Mercurial 或 Subversion 中拉取代码和文档文件，然后构建和托管我们的文档。我们将在项目中使用 GitHub，因为它是访问代码最常用的系统。

首先，我们将创建一个“阅读文档”账号，并关联该 GitHub 账号。然后，我们将选择要为其构建文档的 GitHub 代码库，此时就会出现神奇的效果。

阅读文档后，您将： - 克隆我们的代码库。 - 从主分支构建文档的 HTML、PDF 和 ePub 版本。 - 为我们的文档编制索引，以便进行全文搜索。- 根据代码库中的每个标记和分支创建版本对象，以便我们根据需要托管这些对象。 - 在我们的代码库上激活网络钩子，这样，当我们将代码推送到任何分支时，我们的文档都会重新构建。

Sphinx 是一款权威的文档生成器，具有许多适用于编写技术文档的强大功能，包括： - 生成网页、可打印的 PDF 文件、电子阅读器文档 (ePub) 等均来自相同的来源。 - 我们可以使用 reStructuredText 编写文档。 - 包含交叉引用代码和文档的庞大系统。 - 语法突出显示的代码示例。 - 由第一方和第三方扩展程序组成的蓬勃生态系统。

我将先将两本采用 docbook 格式的 PCP 图书转换为 rst 格式，然后将 REST API 文档从手册格式转换为 rst 格式，再将 pbench Markdown 内容转换为 rst 格式，最后将所有这些内容托管在 readthedocs 网站上。远期目标是改进文档中的图表。

2.1. 转换为 reStructuredText 格式：第一步是将文档内容转换为 reStructuredText 格式。每个章节都有一个单独的 rst 文件，该文件仅包含该章节的内容。例如，《效果助手用户指南和管理员指南》一书包含八章。这意味着，将有八个不同的 rst 文件与这八个章节相对应。rst 文件的名称将与章节名称相同，以免日后造成混淆。三个不同的 rst 文件中将包含一系列图表、表格和示例。rst 内容将以与当前显示方式相同的方式完全添加超链接。REST API 文档和 pbench 内容也将采用相同的命名方式。在将内容转换为 rst 格式时，系统会处理所有必要事项，例如粗体、斜体、下划线、项目符号、表格、字体大小、代码样式、图片大小、对齐方式等。

2.2. 将 rst 与 Sphinx 集成：

ReadtheDocs 默认使用 Sphinx 和 reStructuredText (rst)。由于我的系统中预安装了 Sphinx，因此我将先在项目中创建一个目录（命名为“Performance Co-Pilot Documentation”）来存放文档： $ cd /path/to/project $ mkdir docs

然后，在其中运行 sphinx-quickstart： $ cd docs $ sphinx-quickstart

本快速入门将逐步介绍如何创建必要的配置；在大多数情况下，我们只需接受默认值即可（但在必要时，我们可以在配置文件中进行必要的更改）。完成后，我们将获得 index.rst、conf.py 和一些其他文件。在 index.rst 中，我将添加有关效果助手的所有必要详细信息，并为图书、REST API 文档和 pbench 指南创建标题。当用户点击任何标题时，系统会打开该标题下的所有文档资料。

注意：首页的设计将根据导师和社区成员的意见进行，并会根据需要和要求进行更改。

index.rst 将被内置到文档输出目录（通常为 _build/html/index.html）中的 index.html 中。在公共代码库中创建 Sphinx 文档后，我们就可以开始导入文档，以便使用 Read the Docs。

当我们在文档中添加任何 .rst 文件时，系统会根据该文件生成另外三个文件：一个位于扩展名为 .doctree 的文档树文件夹中，第二个位于扩展名为 .html 的 html 文件夹中，第三个位于扩展名为 .rst.txt 的 html/_sources 文件夹中。

  1. 托管文档：在互联网上托管文档包含以下两个步骤： 1. 导入文档：首先，我会将 Read The Google 文档账号与 GitHub 关联，并导入我们的文档项目以进行构建。 2. 构建文档：完成导入流程后几秒钟内，系统就会自动从我们的公共代码库中提取代码，并构建文档。

  2. Webhook：Read the Docs 用于检测文档和版本更改的主要方法是使用 webhook。Webhook 是通过我们的代码库提供程序（例如 GitHub）配置的，每当代码库发生提交、合并或其他更改时，Read the Docs 都会收到通知。当我们收到 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/zh_CN/latest/ 代码 - https://github.com/arzoo14/PCP_Books_Demo

我还在代码库中配置了网络钩子，借助于此，在代码库中所做的更改将反映在网站中。

时间表和交付成果

社区互动期 [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 内容转换为 rst 格式。

***2020 年 9 月 28 日至 2020 年 10 月 4 日 [第 3 周] 将程序员指南图书的所有四章的 DocBook 内容转换为 rst 格式。

***从 2020 年 10 月 5 日至 2020 年 10 月 11 日 [第 4 周] - 在 readthedocs 网站上托管这两本 PCP 图书。 - 将 REST API 文档从手册页格式转换为 rst 格式。在此期间，我们将涵盖主要着陆页。- 过去三周和本周的博客（我的 GSoD 项目）。

***2020 年 10 月 12 日至 2020 年 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 日 [第 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 日 [第 8 周] 根据 Pbench 指南，将 Markdown 内容转换为 rst 格式。

***从 2020 年 11 月 9 日至 2020 年 11 月 15 日 [第 9 周] - 继续将 Markdown 内容转换为 rst 格式，以作为 PB 指南。 - 在 readthedocs 网站上托管 pbench 指南。 - 我过去一周和本周在 GSoD 项目的博客。

***2020 年 11 月 16 日至 2020 年 11 月 22 日 [第 10 周] - 在索引页中实现搜索功能，以便在网站中按名称搜索任何内容。 - 拓展目标的开始时间。

***2020 年 11 月 23 日至 2020 年 11 月 30 日 [第 11 周] - 改进了文档中的所有图表。 - 上周和本周的最终博文（关于我的 GSoD 项目）。 - 检查代码库是否符合编码标准。如果不符合，请将其更改为符合标准的字体。

项目最终确定期限 [2020 年 11 月 30 日至 12 月 5 日 ]

  • 铅笔休息时间。处理最后的提交内容，确保一切准确无误。
  • 项目报告（也称为最终成果）的提交。
  • 提交项目成功与否的评估结果以及与导师的合作经验。