このページでは、Google Season of Docs で承認されたテクニカル ライティング プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- AboutCode
- テクニカル ライター:
- ayansinha
- プロジェクト名:
- 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. Scancode 出力形式のビジネスでの使用 ]
- 目標: Scancode 出力形式のビジネスユースケースを説明する GSoD のアイデアリストで、Scancode 出力形式が参考アイデアとして記載されています。このセクションでは、Scancode 出力形式のビジネス ユースケースについて説明します。
- 注: この部分では、Scancode-Toolkit のさまざまなビジネス ユースケースに関する入力とポインタについて、メンターからのサポートが不可欠です。
[ 7. 他の AboutCode プロジェクトでこれらの出力を分析に使用する方法 ]
- 目標: このセクションでは、scancode-toolkit のスキャン結果をさまざまな原因で使用する方法と、そのような機能を提供する Aboutcode ツールの基本的な概要について説明します。
- 基本的な概要:
- Scancode-Workbench この部分では、デスクトップ アプリで結果を可視化する方法と、Scancode-Workbench ドキュメントへのポインタについて説明します。必要に応じて、Scancode-Workbench に必要なドキュメントを追加します。必要に応じて、Scancode-Workbench に必要なドキュメントを追加します。
- Deltacode Scancode の結果を Deltacode が取得して、2 つのコードベース間のファイルレベルの違いを判断する方法。
[ 2. AboutCode ドキュメントの構造の再編成 ]
この部分には、Aboutcode ドキュメントに対するさまざまな変更が含まれています。
[ 1. バージョニング システム ]
[ 1. Scancode-Toolkit のコマンドライン オプション -> 2. バージョニング構造の開始] で、コマンドライン オプションのバージョニングの問題について説明します。ドキュメントの他の部分でも同様のことが必要です。そうしないと、バージョン固有のコマンドや情報が混乱を招く可能性があります。
[ 2. ドキュメントの標準とテストの設定 ]
ドキュメントには、Travis-CI を使用した継続的インテグレーションにより、spinx-build（すべてのページをビルドし、Sphinx 構文エラーをチェックする）とリンクチェック（ドキュメントから他のウェブページへのすべてのリンクをチェックする）のテストがすでに用意されています。（このプルリクエスト #17 で追加）reStructured Text とその他の標準での特定のリンティングのチェックがさらに必要です。これは restructuredtext-lint で実現できますが、さらなる調査が必要であり、GSoD プロジェクトの一環として行われます。
[ 3. [スタートガイド] セクションの追加 ]
これは新規ユーザー向けのスタートガイドとして機能し、Aboutcode プロジェクトを始めるための最も基本的で重要なドキュメントのコンパイルが含まれます。 すべての Aboutcode プロジェクト（Scancode-Toolkit、Scancode-Workbench、Deltacode など）にこのセクションがあります。
[ 4. 4 つのドキュメント機能に応じた再構成 ]
既存のドキュメントは、4 つのドキュメント機能（チュートリアル、ハウツー、リファレンス、説明）で明示的に構造化されていません。必要に応じて、情報、説明、ポインタなどを追加して、それに応じて構造化することを提案します。これは、すべての AboutCode プロジェクトとそのドキュメントに適用されます。以下に、このプロジェクトで実施したい Scancode-Toolkit ドキュメントの再構成の例を 2 つ示します。同様の変更は、ドキュメントの残りの部分にも適用されます。
[ 5. 開発ページの再構成（Scancode-Toolkit） ]
コード/API に関する詳細情報を追加して、デベロッパーにとって使いやすくすることができます。 上記の [ 2. コード スキャンについて説明するディスカッション ] セクションへのリンクを追加できます。これにより、スキャンの仕組みの説明が、スキャンの実行に使用するコードにリンクされます。 これらのフォルダには scancode-toolkit のさまざまな部分が含まれているため、scancode の仕組みに関するディスカッションと組み合わせて、API を使用して個々の使用方法を詳しく説明できます。
- [ cluecode : ライセンス、著作権、URL、メールをスキャンするプラグイン ]
- [ commoncode : ヘルパークラスと関数]
- [ extractcode : さまざまなアーカイブ形式を抽出する ]
- [ formattedcode : さまざまな出力ファイル形式の出力フォーマット ]
- [ licensedcode : ライセンス検出コード ]
- [ packagedcode : さまざまなパッケージ形式の解析 ]
- [ plugincode : プラグイン アーキテクチャのクラス ]
- [ summarycode : 検出されたライセンスのスキャンを要約する ]
- [ textcode : テキスト解析を処理する ]
- [ typecode : ファイル形式の判定を処理する ]
- [ scancode : scancode の CLI と API（コア部分） ]
このサブセクションには、scancode-toolkit のこれらの部分に関する詳細情報/API がサブサブセクションに記載されます。 開発ガイドラインは、別のページまたはサブセクションが少ない別のセクションに記載されます。
[ 6. FAQ ページの再構成（Scancode-Toolkit） ]
現在の FAQ ページには、より適切に回答できる質問があり、個別のハウツー、チュートリアル、リファレンス ドキュメントとして個別に構成する必要があります。
- ScanCode の仕組み この問題は [ 2. コード スキャンについて説明するディスカッション ] で参照されており、詳細な別のセクションになります。
- 検出を強化するために新しいライセンスルールを追加する方法 この問題は、既存のハウツーの改善で説明済みです。ドキュメントはそこに移動されます。
- 新しいライセンス検出ルールを追加する方法 これは別の「ハウツー」投稿として作成し、詳しく説明できます。
- 開発を始める方法 すでに別の開発ページがあり、情報がかなり重複しています。開発ページの再構成については、すでに説明しました。
- 新作をカットする手順 これは、別の「新作をカットする方法」に変換できます。
- プロジェクトに関する一般的な質問に回答し、「ハウツー」 / 「チュートリアル」カテゴリに該当しない FAQ の質問を見つけます。