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

このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。

プロジェクトの概要

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

プロジェクトの説明

概要:

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

提案:

  1. 概要: 現在、Performance Co-Pilot のドキュメントは複数の形式で提供されています。これには、docbook 形式の PCP 書籍、man ページ形式の REST API、マークダウン形式の pbench ガイドが含まれます。そこで、組織の現在のメンテナンス グループは、できる限りメンテナンスフリーで、デベロッパー コミュニティがコンテンツの維持に集中できるように、効率的で簡単な方法を実現できるソリューションが必要であると判断しました。そのため、この Google Season of Docs では、組織の現在のニーズに応じて、次の目標を掲げています。

    1. docbook コンテンツを reStructuredText 形式に変換し、readthedocs サイトでホストする。
    2. REST API ドキュメントを man ページからデベロッパー向けの形式（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 リポジトリを選択します。これにより、魔法のようなことが起こります。

ドキュメントを読む: - リポジトリのクローンを作成する - マスターブランチからドキュメントの HTML、PDF、ePub バージョンをビルドします。- ドキュメントをインデックス登録して全文検索を可能にする。 - リポジトリ内の各タグとブランチから 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 つの異なる rst ファイルがあります。今後混乱を避けるため、rst ファイルの名前は章の名前と同じにします。図、表、例のリストが 3 つの異なる 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 では、Performance Co-Pilot に関する必要な詳細をすべて追加し、書籍、REST API ドキュメント、pbench ガイドの見出しを作成します。ユーザーがいずれかの見出しをクリックすると、その見出しの下にあるすべてのドキュメント マテリアルが開きます。

注: インデックス ページのデザインは、メンターとコミュニティ メンバーの同意に基づいて、ニーズや要件に応じて変更されます。

index.rst は、ドキュメント出力ディレクトリ（通常は _build/html/index.html）の index.html に組み込まれます。Sphinx ドキュメントを公開リポジトリに保存したら、ドキュメントをインポートして「Read the Docs」の使用を開始できます。

ドキュメントに .rst ファイルを追加すると、そのファイルに対応する 3 つのファイルが生成されます。1 つは doctrees フォルダに .doctree 拡張子で、2 つ目は Html フォルダに .html 拡張子で、3 つ目は html/_sources フォルダに .rst.txt 拡張子で生成されます。

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

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

これにより、すべての人（管理者、メンター、コミュニティ貢献者）がコミュニティ ドキュメントを変更、拡張、保守でき、ドキュメントに追加する項目やドキュメントから削除すべき項目を、特定の制限されたユーザーで管理する必要がなくなります。

  1. テーマ: テーマ、レイアウト、デザイン、検索などのその他の HTML 機能は、コミュニティのニーズとガイドラインに沿って設定されます。コミュニティの結束期間中に、コミュニティ メンバーとこれらについて話し合います。
  1. ストレッチ目標: ストレッチ目標として、ドキュメント内の図を改善します。現在、図はほとんどがシンプルな白黒の図です。色、シャドウ、スケーリング、一貫性を高め、画像全体をより整え、プロフェッショナルな外観にします。

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

概念実証として、draw.io を使用してドキュメントに記載されている図の 1 つを改善しました。以下からご確認ください。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 つの異なるウェブサイトにするのかは、コミュニティの結束期間中に話し合われます。

DOC の開発期間 [2020 年 9 月 14 日～ 11 月 30 日 ]

***2020 年 9 月 14 日～ 2020 年 9 月 20 日 [1 週目] ユーザーガイドと管理者ガイドの最初の 4 章の docbook コンテンツを rst 形式に変換。

***2020 年 9 月 21 日～ 2020 年 9 月 27 日 [第 2 週] DocBook コンテンツを、ユーザーと管理者ガイドの次の 4 つの章の rst 形式に変換します。

***2020 年 9 月 28 日～ 2020 年 10 月 4 日 [第 3 週] プログラマー ガイドブックの 4 つの章すべてで、ドキュメントブックの内容を最初の形式に変換します。

***2020 年 10 月 5 日～ 2020 年 10 月 11 日 [第 4 週] - PCP に関する両書籍を readthedocs サイトでホスト。 - REST API ドキュメントをマニュアル ページから 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 Host Services インデックスの 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 ドキュメントのホスティング。- 過去 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 日 ]

  • Pencil の休息時間。最終提出に向けて作業し、すべて問題ないことを確認します。
  • プロジェクト レポート（最終的な成果物）の提出。
  • プロジェクトの成功とメンターの実務経験に関する評価を提出します。