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