このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- AboutCode
- テクニカル ライター:
- ヤンシンハ
- プロジェクト名:
- scancode-toolkit のコマンドライン オプションのリファレンスと、aboutcode.readthedocs.io で AboutCode のドキュメントの構造を再編成
- プロジェクトの期間:
- 標準の期間(3 か月)
プロジェクトの説明
[ 1. Scancode-Toolkit コマンドライン オプション ]
Scancode-Toolkit には、スキャンの実行方法、出力形式、その他いくつかのオプション(ポストスキャン プラグインなど)をカスタマイズするコマンドライン オプションが多数用意されています。現在のところ、これらのオプションについては説明のための適切なドキュメントがなく、「--help」または「-h」フラグでのみ使用可能です。このプロジェクトは、以下について説明する完全なドキュメントを作成することを目的としています。
[ 1. コマンドラインで利用できるすべてのオプション ]
- 目的: コマンドラインで指定可能なすべてのオプションのリスト。
- 基本的な概要: まず、デフォルトのスキャン オプションについて、出力の例を交えて説明します。スキャンの実行方法に関する短いグラフィック/説明。
以降、このデフォルトの動作は、他のオプションによってスキャンと出力がどのように変化するかを示す基準となります。
これらについては詳しく説明します。次のセクションで説明するように、次の情報が含まれます。
[ 2. バージョニングの構成を開始する ]
- 目標: バージョニング システムを導入して、クロスリリースのオプション、API、ドキュメントの変更を適切に維持する。
- 問題: 現在、Wiki と ReadTheDocs ページのドキュメントは古いリリースを対象としており、大幅な再構築が必要です。
- 基本の概要: Scancode-toolkit で更新された部分または更新可能な部分は、以下のとおりです。
- コマンドライン オプション
- API
- ドキュメント(開始予定) コマンドライン オプションと API は、バージョンやリリースごとに変更されています。また、ドキュメントも従わなければなりません。そうしないと、ユーザーに大きな混乱がもたらされます。オプションの変更については、コマンドライン ユーティリティ [--help ] がすでに更新されているため、ドキュメントのバージョンを複製するために使用できます。
[ 3. さまざまなケースでこれらのオプションを使用する方法 ]
- 目標: このセクションでは、さまざまな原因で Scancode-toolkit のスキャン結果を使用する方法と、そのような機能を提供する Scancode-Toolkit オプションに関する基本的な概要を説明します。
- 基本の概要: このセクションでは、さまざまなユースケース シナリオの例と、それらのシナリオで推奨されるオプションについて説明します。
- 注: このパートでは、Scancode- Toolkit のさまざまなユースケースに関する情報とポインタについて、メンターの支援が必要です。
[ 4. これらのオプションによるスキャンと出力での変化 ]
- 目標: このセクションでは、さまざまな原因で Scancode-toolkit のスキャン結果を使用する方法と、そのような機能を提供する Aboutcode ツールに関する基本的な概要を説明します。
- 基本概要: このオプションでは、スキャンの実行方法を変更します。冒頭のセクション [1. [コマンドライン] で使用可能なすべてのオプション] とこのセクションでは、すべてのオプションによるこのデフォルトのシナリオの変更点を比較します。
[ 5. 出力形式とその例 ]
- 目標: このセクションでは、さまざまな原因で Scancode-toolkit のスキャン結果を使用する方法と、そのような機能を提供する Aboutcode ツールに関する基本的な概要を説明します。
- 基本の概要: Scancode-Tool には、スキャン結果を生成するさまざまな出力形式を指定するフラグがあります。-
このパートは - 出力形式について詳しく説明し、
- 出力形式の例を示して、
- 出力形式に対応する他のリンクと出力形式を
- スキャン結果が出力ファイルに保存される仕組み。これには、[ 2. コードスキャンについて解説]。
[ 6. 業務でのスキャンコード出力形式の使用 ]
- 目標: スキャンコード出力形式のビジネス ユースケースを説明する GSoD のアイデアリストでは、参照アイデアとしてスキャンコード出力形式を紹介しています。このセクションでは、同じコードを実装します。
- 注: このパートでは、Scancode-Toolkit のさまざまなビジネス ユースケースに関する情報とポインタに関するメンターの支援が必要です。
[ 7. これらの出力が、詳細な分析のために他の AboutCode プロジェクトでどのように使用されるか ]
- 目標: このセクションでは、さまざまな原因で Scancode-toolkit のスキャン結果を使用する方法と、そのような機能を提供する Aboutcode ツールに関する基本的な概要を説明します。
- 基本の概要:
- Scancode-Workbench このパートでは、デスクトップ アプリでの結果を可視化する方法と、Scancode-Workbench のドキュメントへのポインタについて説明します。必要に応じて、必要なドキュメントを Scancode-Workbench に追加します。
- Deltacode Deltacode がスキャンコードの結果を取得して、2 つのコードベース間のファイルレベルの差を判断する方法。
[ 2. AboutCode のドキュメントの構造を再編成 ]
このパートには、Aboutcode ドキュメントに加えられた多数の変更が含まれています。
[ 1. バージョニング システム ]
[ 1. [Scancode-Toolkit コマンドライン オプション] -> [2. Initiate Versioning Structure] コマンドライン オプションのバージョニングの問題を説明しました。ドキュメントの他の部分にも同様のことが必要となります。これらのセクションには、バージョン固有のコマンドや情報が含まれており、混乱を招く可能性があります。
[ 2. ドキュメントの標準とテストの設定 ]
ドキュメントには、Spinx-build(すべてのページをビルドして全体で Sphinx の構文エラーをチェックする)と、Travis-CI による継続的インテグレーションによるリンク チェック(ドキュメントから他のウェブページへのすべてのリンクを確認)のテストがすでに含まれています。(この pull リクエスト #17 で追加) 再構造化テキストやその他の標準での特定の lint チェックについて、さらにチェックが必要になりました。これは restructuredtext-lint で実現できますが、さらなる調査が必要で、GSoD プロジェクトの一環として実施する予定です。
[ 3. 「はじめに」セクションを追加 ]
初心者向けの開始セクションとして、コード プロジェクトの概要をまとめた基本的かつ重要なドキュメントを集めた内容になっています。 このセクションは、Scancode-Toolkit、Scancode-Workbench、Deltacode など、すべてのアババットコード プロジェクトにあります。
[ 4. 4 つのドキュメント関数に従った再構築 ]
既存のドキュメントは、チュートリアル、ハウツー、リファレンス、説明の 4 つのドキュメント関数で明示的に構造化されていません。それに応じて、より詳しい情報/説明/ポインタを追加して、これらを適切に構成することを提案します。これは、すべての AboutCode プロジェクトとそのドキュメントに当てはまります。以下の 2 つの例は、このプロジェクトで継続したい、提案した Scancode-Toolkit ドキュメントの再構成の例です。残りのドキュメントにも同様の変更が行われます。
[ 5. 開発ページの再構成(スキャンコード ツールキット)]
デベロッパーにとって使いやすいように、コードや API についての詳細情報を追加する可能性はあります。 [ 2. コードスキャン ] セクションについて説明したセクションです。これにより、スキャンの仕組みの説明と、スキャンを実行するために使用するコードがリンクされます。 これらのフォルダにスキャンコード ツールキットのさまざまな部分が含まれるように、個々の使用方法はスキャンコードの仕組みについての説明と併せて API で詳しく説明できます。
- [ cluecode : ライセンス、著作権、URL、メールをスキャンするプラグイン ]
- [commoncode : ヘルパークラスとヘルパー関数]
- [ extractcode : さまざまなアーカイブ形式を抽出します ]
- [ formattedcode : さまざまな出力ファイル形式に対する出力フォーマット ]
- [ライセンスコード : ライセンス検出コード ]
- [ packagescode : さまざまなパッケージ形式の解析 ]
- [ plugincode : プラグイン アーキテクチャのクラス ]
- [ summarycode : 検出されたライセンスのスキャンを要約します ]
- [ textcode : テキスト解析を処理 ]
- [ typecode : ファイル形式の判定を処理する ]
- [スキャンコード : スキャンコード用の CLI と API、そのコア部分 ]
このサブセクションには、Scancode-toolkit のこれらの部分に関する詳細情報や API が適宜記載されます。開発ガイドラインは、別のページまたは小さなサブセクションからなる別のセクションで掲載します。
[ 6. よくある質問ページ(スキャンコード ツールキット)を再構成]
現在「よくある質問」ページには、より適切に回答できる質問があるため、ハウツー、チュートリアル、リファレンス ドキュメントとして別々に構成する必要があります。
- ScanCode の仕組み この問題については、[2. コードスキャンについて説明していきます ] のようにします。これについては、別のセクションで詳しく説明します。
- 拡張検出に新しいライセンス ルールを追加する方法この問題については、既存のハウツーの改善ですでに説明されており、ドキュメントはそこに移動されます。
- 新しいライセンス検出ルールを追加する方法これを個別に「ハウツー」投稿に投稿して、詳しく説明できます。
- 開発を開始する方法 すでに個別の開発ページがあり、情報がかなり重なっています。開発ページの再構成については、すでに説明しました。
- 新しいリリースをカットする手順 これは、別の「新しいリリースをカットする方法」に変換できます。
- プロジェクトに関する一般的な質問に回答し、「ハウツー」や「チュートリアル」のカテゴリに該当しない、よくある質問の他の質問を探してください。