パフォーマンス共同パイロット プロジェクト

このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。

プロジェクトの概要

オープンソースの組織:
パフォーマンスに関する共同パイロット
テクニカル ライター:
arzoo14
プロジェクト名:
図書の改善というストレッチ目標とともに、書籍プロジェクト分野のコンテンツを readthedocs 形式と reStructuredText 形式に変換します。
プロジェクトの期間:
標準の期間（3 か月）

プロジェクトの説明

概要:

構造化されたコミュニティ ウェブサイトは、コミュニティが提供するサービス、貴重な貢献、スキル、ドキュメント、チュートリアルなどのアイデアを広めるため、オープンソース組織において重要な役割を果たします。そのため私のプロジェクトでは、書籍プロジェクト領域のコンテンツ（ドキュメント コンテンツ、REST API などのコンテンツをホストできるドキュメント形式など）を転送して更新することで、すべてのオープンソース コントリビューターのユーザビリティと使いやすさの向上を目指します。このプロジェクトは、コミュニティ貢献者がコンテンツの変更や拡張をより簡単に行えるようにもなります。また、ストレッチ目標として、ドキュメントの図表も改善され、よりプロフェッショナルな外観になります。

提案:

  1. 概要: Performance Co-Pilot のドキュメントには、現在、いくつかの異なる形式があります。これには、docbook 形式の PCP 書籍、manpage 形式の REST API、マークダウン形式の pbench ガイドが含まれます。そのため、組織の現在のメンテナンス担当者グループは、可能な限りメンテナンスが不要なソリューションが必要だと判断し、デベロッパー コミュニティが合理的かつ簡単な方法でコンテンツのメンテナンスに完全に集中できるようにすることにしました。現在の Google ニーズに即して、Google ドキュメント シーズン中に以下の目標を設定する予定です。

    1. docbook のコンテンツを reStructuredText 形式に変換し、readthedocs サイトでホストします。
    2. REST API ドキュメントをマニュアルページからデベロッパー向けの形式（reStructuredText 形式）に変換し、readthedocs サイトでホストします。
    3. pbench MarkDown コンテンツを reStructuredText 形式に変換し、readthedocs サイトでホストします。
    4. ストレッチの目標は、ドキュメント内の図を改良することです。

  2. 実装: 現在、Performance Co-Pilot のドキュメントは特定の形式では用意されていません。ドキュメントの内容を変更する必要がある場合は、制限されたユーザーによって変更される必要があります。積極的なコミュニティ メンバーがドキュメントのコンテンツを変更、拡張することはそれほど容易ではありません。

この GSoD では、reStructuredText 形式、Read the Docs（RTD）、Sphinx の力を借りて、組織がこれらの制限を克服できるようにしたいと思います。

Read the Docs（RTD）は、ドキュメントのビルド、バージョニング、ホスティングを自動化することで、ソフトウェア ドキュメントを簡素化します。これは、Sphinx で生成されたドキュメント用のホスティング プラットフォームです。Sphinx の機能に加え、バージョン管理、全文検索、その他の便利な機能が追加されています。Git、Mercurial、または Subversion からコードとドキュメント ファイルを pull し、ドキュメントをビルドしてホストします。今回は、コードにアクセスするために最もよく使用されるシステムである GitHub を使用します。

まず、Read the Docs アカウントを作成し、GitHub アカウントをリンクします。次に、ドキュメントを作成する GitHub リポジトリを選択します。この時点で、魔法の始まりです。

ドキュメントの読み上げ: - リポジトリのクローンを作成します。 - master ブランチから HTML、PDF、ePub バージョンのドキュメントを作成する。 - 全文検索ができるように、Google ドキュメントをインデックスに登録します。 - リポジトリの各タグやブランチから Version オブジェクトを作成し、必要に応じてホストできるようにします。 - リポジトリで Webhook を有効にします。これにより、コードを任意のブランチに push したときに、ドキュメントが再構築されます。

Sphinx は、技術ドキュメントを作成するための多くの優れた機能を備えた、信頼できるドキュメント生成ツールです。たとえば、ウェブページ、印刷可能な PDF、電子書籍リーダー用ドキュメント（ePub）などを同じソースから生成できます。- reStructuredText を使用してドキュメントを作成できます。- 相互参照コードとドキュメントの広範なシステム。 - 構文がハイライト表示されたコードサンプル。 - 自社拡張機能とサードパーティの拡張機能からなる活気に満ちたエコシステム。

まず、docbook 形式にある 2 つの PCP 書籍を rst 形式に変換し、次に REST API ドキュメントを man ページ形式から rst 形式に変換してから、pbench マークダウン コンテンツを rst 形式に変換し、最後にこれらすべてを readthedocs サイトでホストします。ストレッチ目標は、ドキュメント内の図を改良することです。

2.1. reStructuredText 形式への変換: 最初のステップとして、ドキュメント コンテンツを reStructuredText 形式に変換します。チャプターごとに個別の rst ファイルがあり、各チャプターの内容だけを含めます。たとえば、Performance Co-Pilot User's and Administrator's Guide の書籍には 8 つの章があります。つまり、この 8 つのチャプターに対応する 8 つの異なる最初のファイルがあります。混乱を避けるために、最初のファイルの名前はチャプター名と同じにします。図、表、例の一覧は、3 つの異なる 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 ファイルを追加すると、そのファイルに対応する 3 つのファイルが生成されます。1 つは .doctree 拡張子の doctrees フォルダ、2 つ目は .html 拡張子の HTML フォルダ、3 つ目は html/_sources フォルダ内の .rst.txt 拡張子です。

  1. ドキュメントのホスティング: インターネット上でのドキュメントのホスティングは、次の 2 つのステップで構成されます。 1. ドキュメントのインポート: 最初のステップとして、Read The Docs アカウントを GitHub に接続し、ドキュメント プロジェクトをインポートしてビルドします。2. ドキュメントのビルド: インポート プロセスの完了から数秒以内に、コードが公開リポジトリから自動的に取得され、ドキュメントがビルドされます。

  2. ウェブフック: Read the Docs でドキュメントやバージョンへの変更を検出するために使用する主な方法は、Webhook を使用することです。Webhook は、GitHub などのリポジトリ プロバイダを使用して構成され、リポジトリに対する commit、マージ、その他の変更が行われるたびに、Read the Docs に通知されます。Webhook 通知を受信すると、その変更がプロジェクトのアクティブなバージョンに関連していると判断され、関連している場合はそのバージョンに対してビルドがトリガーされます。

このようにして、だれでも（管理者、メンター、コミュニティ貢献者）がコミュニティ ドキュメントを変更、拡張、または保守でき、ドキュメントに追加すべき内容やドキュメントから削除すべき内容を管理するために特定の制限されたユーザーセットは必要ありません。

  1. テーマ: テーマ、レイアウト、デザイン、その他の HTML 機能（検索など）は、コミュニティのニーズとガイドラインに準じます。コミュニティの絆を深める段階で、これらすべてのことをコミュニティ メンバーと話し合います。
  1. ストレッチ目標: ストレッチ目標として、ドキュメントに記載されている図を見直します。現在、これらの図は主に単純なモノクロの描画です。色、シェーディング、拡大縮小、整合性を持たせ、一般的により洗練された、よりプロフェッショナルな画像にします。

この目的のため、draw.io（またはメンターの同意を得たその他のツール）を使用します。

概念実証として、ドキュメント内の図の 1 つを 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 日 ]

この時間をかけてコミュニティになじみ、ドキュメントを確認し、メンターとさまざまなことについて話し合って、プロセスの早い段階で不適切な決定が行われないようにします。この期間中に、テーマ、レイアウト、デザイン、検索機能やナビゲーション バーなどの機能について、メンターやコミュニティ メンバーと話し合います。プロジェクトの名称と、3 つのトピックをすべてホストする単一のウェブサイト、または 3 つのトピックに対応する 3 つの異なるウェブサイトのどちらにするかの決定は、コミュニティの絆を深めるときに検討します。

ドキュメント作成期間 [2020 年 9 月 14 日～ 11 月 30 日 ]

***2020 年 9 月 14 日～ 2020 年 9 月 20 日 [第 1 週] 「ユーザーと管理者のガイド」ブックの 4 章の docbook コンテンツを rst 形式に変換します。

***2020 年 9 月 21 日～ 2020 年 9 月 27 日 [第 2 週] 『Users and Administrators Guide』の次の 4 章の docbook コンテンツを rst 形式に変換。

***2020 年 9 月 28 日～ 2020 年 10 月 4 日 [第 3 週] プログラマーズ ガイドブックの 4 章すべてについて、Docbook のコンテンツを rst 形式に変換します。

***2020 年 10 月 5 日～ 10 月 11 日 [第 4 週] - Readthedocs サイトで両方の PCP 書籍をホストします。- REST API ドキュメントを man ページから rst 形式に変換しました。この期間中は、メインのランディング ページが対象になります。 - 過去 3 週間と今週の（私の 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 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/metrics

***2020 年 10 月 26 日～ 2020 年 11 月 1 日 [第 7 週] - 過去数週間に残るものがある場合、その期間が先になります。 - readthedocs サイトで REST API ドキュメントのホスティング。 - 過去 2 週間と今週の（私の GSoD プロジェクトの）ブログ

***2020 年 11 月 2 日～ 2020 年 11 月 8 日 [第 8 週] マークダウン コンテンツを pbench ガイドの rst 形式に変換。

***2020 年 11 月 9 日から 2020 年 11 月 15 日 [第 9 週] - 引き続き、マークダウン コンテンツを pbench ガイドの rst 形式に変換。 - readthedocs サイトで pbench ガイドをホストします。 - 前週と今週の（GSoD プロジェクトの）ブログ

***2020 年 11 月 16 日～ 2020 年 11 月 22 日 [第 10 週] - インデックス ページに検索機能を実装し、ウェブサイト内のコンテンツ名からコンテンツを検索できるようにします。- ストレッチ目標の開始。

***2020 年 11 月 23 日～ 2020 年 11 月 30 日 [第 11 週] - ドキュメント内の図をすべて改善。 - 前週と今週の（私の GSoD プロジェクトに関する）最後のブログ。 - コードベースがコーディング標準に準拠しているかどうかを確認する。そうでない場合は、標準に変更します。

プロジェクトの最終調整期間 [2020 年 11 月 30 日～ 12 月 5 日 ]

  • 鉛筆の休息時間。最終的な送信に取り組み、問題がないことを確認します。
  • プロジェクト レポート（最終成果物とも呼ばれます）の提出
  • プロジェクトの成功およびメンターとの実務経験の評価を提出します。