效果联合试行项目

本页面包含有关 Google 文档季可接受的技术写作项目的详细信息。

项目摘要

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

Project description

摘要：

社区网站在开源组织中发挥着重要作用，因为它传播了社区提供的产品、他们的宝贵贡献、技能、文档和教程等的理念。因此，我的项目旨在通过传输和更新图书项目领域的内容（即文档书内容、可以阅读的结构化网站格式、REST API Markdown 文档和 pbench 等现代文档），提高所有开源贡献者的易用性和易用性。此项目也会让社区贡献者能够更轻松地更改和扩展这些内容，从而让他们受益。作为一个延伸目标，本文档中的图表也将进行改进，使其看起来更专业。

提案：

  1. 概述：性能助理驾驶员文档目前以多种不同的格式提供。其中包括 docbook 格式的 PCP 图书、采用手册格式的 REST API 以及 Markdown 格式的 pbench 指南。因此，该组织的当前维护人员团队发现他们需要一个尽可能免维护的解决方案，以便开发者社区可以完全专注于以精简的方式维护其内容。 因此，根据该组织的当前需求，我将在这个 Google 文档使用季实现以下目标：

    1. 将文档手册内容转换为 reStructuredText 格式，并将其托管在 readthedocs 网站上。
    2. 将 REST API 文档从手册页转换为对开发者友好的格式，即 reStructuredText 格式并将其托管在 readthedocs 网站上。
    3. 将 pbench MarkDown 内容转换为 reStructuredText 格式，并将其托管在 readthedocs 网站上。
    4. 扩展目标是改进文档中显示的图表。

  2. 实施： 目前，性能助理试行计划文档并未以特定格式提供。每当需要更改文档内容时，需要由一组受限的用户进行更改。对于活跃的社区成员而言，更改和扩展文档内容并非易事。

我将让该组织借助 reStructuredText 格式、Read theDocs (RTD) 和 Sphinx 能够在此次 GSoD 测试期间克服这些限制。

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

首先，我们将创建一个“阅读 Google 文档”帐号，然后关联 GitHub 帐号。然后，我们选择想要为其构建文档的 GitHub 代码库，然后便会产生奇迹。

阅读文档将会： - 克隆我们的代码库。 - 通过我们的 master 分支制作 HTML、PDF 和 ePub 版本的文档。 - 将我们的文档编入索引，以便进行全文搜索。 - 根据代码库中的每个标记和分支创建 Version 对象，以便我们选择性地托管这些对象。 - 激活代码库中的 webhook，以便当我们将代码推送到任何分支时，我们的文档都会重新构建。

Sphinx 是一个权威的文档生成器，在撰写技术文档时具有许多出色的功能，包括： - 生成网页、可打印的 PDF、适用于电子阅读器的文档 (ePub)，等等。 - 我们可以使用 reStructuredText 编写文档。 - 一个广泛的交叉引用代码和文档系统。 - 语法突出显示的代码示例。 - 一个由第一方和第三方扩展程序组成的生机勃勃的生态系统。

首先，我将以文档格式显示的两本 PCP 图书转换为 rst 格式，接着将 REST API 文档从手册页面格式转换为 rst 格式，再将 pbench Markdown 内容转换为 rst 格式，最后，将所有这些内容都托管在 readthedocs 网站上。扩展目标是改进文档中的图表。

2.1. 转换为 reStructuredText 格式：第一步是将文档内容转换为 reStructuredText 格式。每个章节都有一个单独的第一个文件，其中只包含该章节的内容。例如，《性能助理驾驶员的用户指南》和《管理员指南》一书就包括八个章节。这意味着将有 8 个不同的 rst 文件，分别对应这 8 个章节。第一个文件的名称将与章节名称相同，以免日后出现任何混淆。图表、表格和示例列表将显示在三个不同的 RST 文件中。第一部分将采用超链接的形式，与目前显示的方式完全相同。REST API 文档和 pbench 内容也将使用同样的内容。在将内容转换为原始格式时，会处理所有必要设置（例如粗体、斜体、下划线、项目符号、表格、字体大小、代码样式、图片大小、对齐方式等）。

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 中，我将添加关于 Performance Co-Pilot 的所有必要详细信息，并为图书、REST API 文档和 pbench 指南创建标题。当用户点击任何标题时，即会打开该标题下的所有文档资料。

请注意：索引页面的设计将根据导师和社区成员的同意情况进行设计，并根据需求和要求进行更改。

index.rst 将内置到我们文档输出目录（通常是 _build/html/index.html）中的 index.html 中。将 Sphinx 文档放入公共存储库后，我们就可以通过导入文档来开始使用“阅读文档”功能。

如果我们在文档中添加任何 .rst 文件，那么对应于该文件会生成另外三个文件：一个在扩展名为 .doctree 的 doctrees 文件夹中，第二个在扩展名为 .html 的 html 文件夹中，第三个在扩展名为 .rst.txt 的 html/_sources 文件夹中。

  1. 托管文档： 在互联网上托管文档包含两个步骤： 1. 导入文档：首先，我将“Read TheDocs”帐号与 GitHub 相关联，然后导入要构建的文档项目。2. 构建文档：在完成导入过程的几秒钟内，系统将自动从我们的公开代码库中提取代码并构建文档。

  2. WEBHOOKS： 阅读 Google 文档用于检测文档和版本的更改的主要方法是使用 webhook。网络钩子是通过我们的代码库提供程序（例如 GitHub）配置的，并且每当对代码库进行提交、合并或其他更改时，系统都会通知“阅读文档”。当我们收到 webhook 通知时，我们会确定更改是否与项目的活跃版本相关，如果有，则针对该版本触发构建。

这样，任何人（管理员、导师、社区贡献者）都可以更改、扩展或维护社区文档，并且不需要一组特定受限的用户来处理应添加到文档或应从文档中移除的内容。

  1. 主题： 主题、布局、设计和其他 HTML 功能（如搜索）将符合社区的需求和指南。在培养社群期间，我会与社群成员讨论所有这些事情。
  1. 扩展目标： 作为扩展目标，我会改进文档中的图表。目前，图表大多是简单的黑白绘图。我会引入更多颜色、阴影、缩放和一致性，并使图片通常更简洁 / 更专业。

为此，我将使用 draw.io（或获得导师同意的任何其他工具）。

作为概念验证，我借助 draw.io 改进了文档中显示的一个图表。请访问以下网址：https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

概念证明

我已将 PCP 图书的一小部分（文档格式）转换为 rst 格式，并将其托管在 readthedocs 网站上。您可以在此处找到。

网站 - https://pcp-books.readthedocs.io/en/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 周] 将《用户和管理员指南》一书前四个章节的文档簿内容转换为第一格式。

***2020 年 9 月 21 日至 2020 年 9 月 27 日 [第 2 周] 将文档手册内容转换为第一格式，用于《用户和管理员指南》一书接下来的四个章节。

***2020 年 9 月 28 日到 2020 年 10 月 4 日 [第 3 周] 将《程序员指南》图书全部四章的文档簿内容转换为第一格式。

***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 周] 将 Markdown 内容转换为 pbench 指南的第一格式。

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

***2020 年 11 月 16 日至 2020 年 11 月 22 日 [第 10 周] - 在索引页面中实现搜索功能，搜索网站名称中包含其名称的任何内容。 - 开始伸展目标。

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

项目完结期 [2020 年 11 月 30 日 - 2020 年 12 月 5 日 ]

  • 铅笔停工。正在处理最终的提交内容，并确保一切正常。
  • 提交项目报告，也称为最终工作产品。
  • 提交关于项目成功与导师的工作经验的评估结果。