AboutCode プロジェクト
コレクションでコンテンツを整理
必要に応じて、コンテンツの保存と分類を行います。
このページには、Google Season of Docs で承認されたテクニカル ライティング プロジェクトの詳細が掲載されています。
プロジェクトの概要
- オープンソースの組織:
- AboutCode
- テクニカル ライター:
- ayansinha
- プロジェクト名:
- scancode- Toolkit のコマンドライン オプションのリファレンスと、aboutcode.readthedocs.io にある AboutCode ドキュメントの構造の再編成
- プロジェクトの長さ:
- 標準期間（3 か月）
プロジェクトの説明
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. すべてのオプションがこのデフォルトのシナリオに与える影響を比較します。
- 目標：このセクションでは、scancode- Toolkit のスキャン結果がさまざまな原因で使用される方法の基本的な概要と、そのような機能を提供する Aboutcode ツールについて説明します。
- 基本概要: Scancode-Tool には、スキャン結果を生成するさまざまな出力形式を指定するフラグがあります。以下にその例を示します。
この部分は
- 出力形式について詳しく
- 出力形式の例を示す
- 出力形式とその用途に対応する他のリンクを提供する
- スキャン結果が出力ファイルに保存される方法。これは、さまざまな形式の生成方法にもリンクしています。詳しくは、[ 2. コード スキャンの説明に関するディスカッション] をご覧ください。
- 目標: 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. コードスキャンについて説明します]。詳細については、完全に別のセクションです。
- 高度な検出用の新しいライセンス ルールを追加する方法この問題については、既存のハウツーの改善ですでに説明しています。ドキュメントはそちらに移動されます。
- 新しいライセンス検出ルールを追加する方法これは、別途「方法」として投稿し、詳しく説明することもできます。
- 開発を開始する方法すでに別の開発ページがあり、情報の重複がかなりあります。開発ページの再構成については、すでに上記で説明しています。
- 新しいリリースの切り抜き手順
これは、独立した「新しいリリースの切り抜き方法」に変換できます。
- プロジェクトに関する一般的な質問に回答し、「方法」や「チュートリアル」のカテゴリに該当しないよくある質問を追加します。
特に記載のない限り、このページのコンテンツはクリエイティブ・コモンズの表示 4.0 ライセンスにより使用許諾されます。詳しくは、Google Developers サイトのポリシーをご覧ください。Java は Oracle および関連会社の登録商標です。
最終更新日 2025-07-25 UTC。
[null,null,["最終更新日 2025-07-25 UTC。"],[[["\u003cp\u003eThis project focuses on enhancing the documentation for the Scancode-Toolkit, an open-source tool by AboutCode used for code analysis.\u003c/p\u003e\n"],["\u003cp\u003eThe project aims to create comprehensive documentation for Scancode-Toolkit's command line options, including their use cases and impact on scan results.\u003c/p\u003e\n"],["\u003cp\u003eA key aspect of the project involves restructuring AboutCode's documentation to improve organization, introduce versioning, and establish documentation standards.\u003c/p\u003e\n"],["\u003cp\u003eThe project also includes a section on business use cases of Scancode output formats and how other AboutCode projects utilize Scancode's results.\u003c/p\u003e\n"],["\u003cp\u003eThis initiative aims to make the documentation more user-friendly, accessible and comprehensive for both newcomers and experienced developers.\u003c/p\u003e\n"]]],["This technical writing project aims to enhance the documentation for AboutCode's scancode-toolkit. Key actions include: documenting all command-line options, initiating a versioning system for options, APIs, and documentation, illustrating use cases and output format details, and explaining business applications. Additionally, it involves reorganizing AboutCode documentation by implementing a versioning system, adding a \"Getting Started\" section, restructuring content according to document functions, enhancing the development page, and restructuring the FAQ page.\n"],null,["# AboutCode project\n\nThis page contains the details of a technical writing project accepted for\nGoogle Season of Docs.\n\n### Project summary\n\nOpen source organization:\n: AboutCode\n\nTechnical writer:\n: ayansinha\n\nProject name:\n: Reference for Command Line Options in scancode-toolkit and Reorganize the structure of AboutCode documentation at aboutcode.readthedocs.io\n\nProject length:\n: Standard length (3 months)\n\n### Project description\n\n\\[ 1. Scancode-Toolkit Command Line Options \\]\n----------------------------------------------\n\nScancode-Toolkit has a host of Command Line options to customize how the scan is performed, the output format and several other options like post-scan plugins. These options currently don't have proper documentation to explain them and are only available through the \"--help\" or \"-h\" flag. This project aims to make complete documentation that explains:\n\n### \\[ 1. All the Options available through Command Line \\]\n\n- Goal: An exhaustive list of all possible options through the command line.\n- Basic Overview: First, the default scan options are discussed, with an example of the output. A short graphic/description on how the scan is performed. \n Hereafter, this default behavior acts as a reference to how the other options change the scan and the output. \n These are to be discussed in detail and will contain the following information as mentioned in the next sections.\n\n### \\[ 2. Initiate Versioning Structure \\]\n\n- Goal: Initiate a versioning system to properly maintain cross-release options/API and documentation changes.\n- Problem: Presently the documentation in the wiki and the ReadTheDocs pages are for older releases and needs major restructuring.\n- Basic Overview: The parts of the scancode-toolkit that have been updated/could be updated in version are\n- Command Line Options\n- APIs\n- Documentation (To be initiated) The command line options and the APIs are changed in versions and releases, and the documentation also has to follow, or it will create massive confusion for the users. The command line utility \\[ --help \\] already is updated for any changes in options and could be used to replicate the versioning in the documentation.\n\n### \\[ 3. How these Options can be used in different cases \\]\n\n- Goal: This section will provide a basic summary of how the scan results of scancode-toolkit can be used in different causes and the Scancode-Toolkit options that provide such functionality.\n- Basic Overview: This section gives different use case scenario examples and what options are recommended in those scenarios.\n- Note: This part requires significant help from the mentor in terms of inputs about and pointers to various use cases of Scancode-Toolkit.\n\n### \\[ 4. What these Options change in the Scan and the Output \\]\n\n- Goal: This section will provide a basic summary of how the scan results of scancode-toolkit can be used in different causes, and the Aboutcode tools that provide such functionality.\n- Basic Overview: The options change the behavior of how the scan is performed. A basic default case will be illustrated in the leading section \\[ 1. All the Options available through Command Line \\] and this section will compare the changes that all the options bring to this default scenario.\n\n### \\[ 5. Output Formats and their examples \\]\n\n- Goal: This section will provide a basic summary of how the scan results of scancode-toolkit can be used in different causes, and the Aboutcode tools that provide such functionality.\n- Basic Overview: Scancode-Tool has flags to specify different output formats in which the scan results will be generated. These are - \n This part will\n- explain in detail the output formats\n- give examples on the output formats\n- give other links corresponding to the output format and its use\n- how scan results are stored in the output files. This also links to How these different formats are generated, which will be explained in \\[ 2. Discussions explaining Code Scanning \\].\n\n### \\[ 6. Business Use of Scancode Output Formats \\]\n\n- Goals: Explain the Business Use cases of Scancode Output formats In the GSoD ideas list, Scancode Output Formats is mentioned as a reference idea. This section implements the same.\n- Note: This part requires significant help from the mentor in terms of inputs about and pointers to various business use cases of Scancode-Toolkit.\n\n### \\[ 7. How these outputs are used by other AboutCode projects for more analysis \\]\n\n- Goal: This section will provide a basic summary of how the scan results of scancode-toolkit can be used in different causes, and the Aboutcode tools that provide such functionality.\n- Basic Overview:\n- Scancode-Workbench This part explains visualizing results with the desktop app and pointers to scancode-workbench documentation for more support on the same. Will add required documentation to scancode-workbench if necessary.\n- Deltacode How scancode results are taken by Deltacode to determine file level differences between two codebases.\n\n\\[ 2. Reorganize the structure of AboutCode Documentation \\]\n------------------------------------------------------------\n\nThis part includes a host of changes to the Aboutcode Documentation\n\n### \\[ 1. Versioning system \\]\n\nIn \\[ 1. Scancode-Toolkit Command Line Options -\\\u003e 2. Initiate Versioning Structure\\] the issue of versioning the Command Line options are mentioned. The same is necessary for other parts of the documentation also which contain version specific commands/information that would otherwise create confusion.\n\n### \\[ 2. Setting Documentation Standards and Tests \\]\n\nThe documentation already has tests for spinx-build (builds all the pages and checks for Sphinx syntax errors throughout) and link check (Checks all the links to other webpages from the documentation) with Continuous Integration through Travis-CI. (Added by me in this Pull Request #17 )\nNow it needs more checks for specific linting in reStructured Text and other standards. This could be achieved with restructuredtext-lint but needs more research and will be done as a part of my GSoD project.\n\n### \\[ 3. Adding a \"Getting Started\" Section \\]\n\nThis will act as a starting section for newcomers and will contain a compilation of the most basic and important documents to get started with Aboutcode Projects.\nEvery Aboutcode Project will have this section including Scancode-Toolkit, Scancode-Workbench, Deltacode, and others.\n\n### \\[ 4. Restructuring According to the 4 Document Functions \\]\n\nThe existing Documentation isn't explicitly structured in the 4 document functions - Tutorials, How To's, Reference and Explanations. I propose to structure those accordingly, adding more information/explanations/pointers whatever necessary. This holds for all the AboutCode projects and their documentation. Below are two examples of the Scancode-Toolkit documentation restructuring I propose and would like to carry on in this project. Similar changes will be carried out on the rest of the documentation.\n\n### \\[ 5. Restructuring the Development Page (Scancode-Toolkit) \\]\n\nMore info on the Code/APIs could be added to make it more developer friendly.\nThere can be links to the \\[ 2. Discussions explaining the Code Scanning \\] section above. This links the explanation of how the scan works to the code it uses to perform the scan.\nLike these folders contain different parts of scancode-toolkit, their individual use can be elaborated with the APIs, in conjunction with the Discussion on how scancode works.\n\n- \\[ cluecode : plugins for scanning licenses, copyrights, urls, emails \\]\n- \\[ commoncode : helper classes and functions\\]\n- \\[ extractcode : extracts different archive formats \\]\n- \\[ formattedcode : output formatting for different output file formats \\]\n- \\[ licensedcode : licence detection code \\]\n- \\[ packagedcode : parsing various package formats \\]\n- \\[ plugincode : classes for the plugins architecture \\]\n- \\[ summarycode : summarizes scan on detected licenses \\]\n- \\[ textcode : handles text parsing \\]\n- \\[ typecode : handles file type determinations \\]\n- \\[ scancode : CLI and API to scancode, the core part \\]\n\nThis subsection will contain detailed information/APIs on these parts of scancode-toolkit in subsubsections accordingly.\nThe Development guidelines will be there in another page or another section having smaller subsections.\n\n### \\[ 6. Restructuring the FAQ page (Scancode-Toolkit) \\]\n\nThe FAQ page at present has questions which can be better answered and should be structured as separate How To's, Tutorials and Reference documents separately.\n\n- How does ScanCode work? This issue is referenced in \\[ 2. Discussions explaining the Code Scanning \\] and will be an entirely separate section in much more details.\n- How to Add New License Rules for Enhanced Detection? This issue is already discussed before in Improving the existing How-To's, documentation will be moved there.\n- How to add a new license detection rule? This could be made into another \"How To\" post separately and could be elaborated on.\n- How To get started with Development? There's already a separate development page and the information overlaps quite a lot. The restructuring of the development page has already been discussed above.\n- Steps to cut a new release This can be transformed into a separate \"How To Cut a new release\".\n- Find more FAQ questions which answer generic questions about the project and doesn't fall in the \"How To\"/\"Tutorial\" categories."]]
