diff --git a/docs/source/cli-reference/basic-options.rst b/docs/source/cli-reference/basic-options.rst index 313e888558..961dff7021 100644 --- a/docs/source/cli-reference/basic-options.rst +++ b/docs/source/cli-reference/basic-options.rst @@ -538,6 +538,12 @@ The option ``--license-text-diagnostics`` is a sub-option of ``--license-text``. + .. admonition:: Attention + + The option ``--license-text`` will not work with the ``--csv`` + output as outputting full license texts in a CSV file doesn't serve + a practical purpose. + With the ``--license-text`` option, the scan results attribute "matched text" includes the matched text for the detected license. diff --git a/docs/source/cli-reference/output-format.rst b/docs/source/cli-reference/output-format.rst index 753d45aa52..bda76e4554 100644 --- a/docs/source/cli-reference/output-format.rst +++ b/docs/source/cli-reference/output-format.rst @@ -199,7 +199,7 @@ following options. "scan_errors": [] }, - This is the recommended Output option for ScanCode Toolkit. + This is the recommended Output option for ScanCode-Toolkit. ---- diff --git a/docs/source/cli-reference/scan-options-post.rst b/docs/source/cli-reference/scan-options-post.rst index 195ce5bdac..fdca3ccdd0 100644 --- a/docs/source/cli-reference/scan-options-post.rst +++ b/docs/source/cli-reference/scan-options-post.rst @@ -53,7 +53,7 @@ To see all plugins available via command line help, use ``--plugins``. .. note:: The ``--consolidate`` option will be deprecated in a future version of - ScanCode Toolkit as top level packages, dependencies and licenses + ScanCode-Toolkit as top level packages, dependencies and licenses now provide improved consolidated data. The JSON file containing scan results after using the ``--consolidate`` Plugin is structured as diff --git a/docs/source/cli-reference/synopsis.rst b/docs/source/cli-reference/synopsis.rst index c3845f1095..ea211e966a 100644 --- a/docs/source/cli-reference/synopsis.rst +++ b/docs/source/cli-reference/synopsis.rst @@ -7,11 +7,11 @@ ScanCode detects licenses, copyrights, package manifests and direct dependencies in source code and binary files, by scanning the files. This page introduces you to the ScanCode Toolkit Command Line Interface in the following sections: -- Installation -- Quickstart -- Type of Options -- Output Formats -- Other Important Documentation +- :ref:`syn_install` +- :ref:`synopsis_quickstart` +- :ref:`scancode_cli_options` +- :ref:`synopsis_output` +- :ref:`other_imp_doc` .. _syn_install: @@ -26,7 +26,8 @@ detailed Instructions on the each of the Installation Methods. - :ref:`app_install` - :ref:`pip_install` - :ref:`source_code_install` - +- :ref:`docker_install` +- :ref:`fedora_install` .. _synopsis_quickstart: @@ -77,7 +78,7 @@ throughout the documentation. Type of Options --------------- -ScanCode Toolkit Command Line options can be divided into these major sections: +ScanCode-Toolkit Command Line options can be divided into these major sections: - :ref:`cli_basic` - :ref:`Extractcode Options ` @@ -94,18 +95,27 @@ Line Options listed under each section. Output Formats -------------- -The output file format is set by using the various output options. The recommended output format -is JSON. If ``--json`` is used, the entire file being in one line, without whitespace characters. +The output file format is set by using the various output options. See +:doc:`../rst_snippets/output_format_options` . The recommended output +format is JSON. + +If ``--json`` is used, the entire file being in one line, without +whitespace characters. If ``--json-pp`` is used, the output is in a +pretty-printed JSON format—structured with indentation and line breaks to +make it more human-readable, rather than compressed into a single line. + +The following example scans will show you how to run a scan with each of +the result formats. For the scans, we will use the ``samples`` directory +provided with the ScanCode-Toolkit, along with the ``--json-pp`` output +option. -The following example scans will show you how to run a scan with each of the result formats. For -the scans, we will use the ``samples`` directory provided with the ScanCode Toolkit. .. include:: /rst_snippets/tip_snippets/stdout.rst JSON file output ^^^^^^^^^^^^^^^^ -Scan the ``samples`` directory and save the scan to a JSON file (pretty-printed)::: +Scan the ``samples`` directory and save the scan to a JSON file (pretty-printed):: scancode -clpieu --json-pp output.json samples @@ -301,4 +311,6 @@ file. When the scan is done, open ``samples.html`` in your web browser. .. image:: data/scancode-toolkit-static-html1.png .. image:: data/scancode-toolkit-static-html2.png +.. _other_imp_doc: + .. include:: /rst_snippets/other_imp_doc.rst diff --git a/docs/source/getting-started/home.rst b/docs/source/getting-started/home.rst index c32b697928..23813d9a62 100644 --- a/docs/source/getting-started/home.rst +++ b/docs/source/getting-started/home.rst @@ -41,7 +41,7 @@ most advanced open source and commercial tools available today for Software Composition Analysis. -What does ScanCode Toolkit do? +What does ScanCode-Toolkit do? ------------------------------ ScanCode detects and normalizes origin, dependencies, licensing and other diff --git a/docs/source/getting-started/install.rst b/docs/source/getting-started/install.rst index ed6ff44861..25b33168a9 100644 --- a/docs/source/getting-started/install.rst +++ b/docs/source/getting-started/install.rst @@ -125,7 +125,7 @@ ScanCode needs a Python 3.9+ interpreter; We support all Python versions from Installation as an Application: Downloading Releases ----------------------------------------------------- -Get the ScanCode Toolkit tarball archive of a specific version and your +Get the ScanCode-Toolkit tarball archive of a specific version and your operating system by going to the `project releases page `_ For example, Version 30.0.1 archive can be obtained from @@ -267,15 +267,16 @@ Un-installation Installation via Docker: ------------------------ -You can install ScanCode Toolkit by building a Docker image from the included Dockerfile. +You can install ScanCode-Toolkit by building a Docker image from the included Dockerfile. The prerequisite is a working `docker installation `_. Download the ScanCode-Toolkit Source Code ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- ``git clone https://github.com/aboutcode-org/scancode-toolkit`` to get the latest - ( :ref:`source_code_install` ) source code. +Run the following once you have `Git `_ installed:: + + git clone https://github.com/aboutcode-org/scancode-toolkit.git Build the Docker image @@ -317,7 +318,7 @@ those after will be forwarded to scancode. Installation from Source Code: Git Clone ----------------------------------------- -You can download the ScanCode Toolkit Source Code and build from it yourself. +You can download the ScanCode-Toolkit Source Code and build from it yourself. This is what you would want to do it if: - You are developing ScanCode or adding new patches or want to run tests. diff --git a/docs/source/getting-started/newcomer.rst b/docs/source/getting-started/newcomer.rst index ffd1b9d70b..b62d242bae 100644 --- a/docs/source/getting-started/newcomer.rst +++ b/docs/source/getting-started/newcomer.rst @@ -38,10 +38,10 @@ Table of Contents .. _newcomer_try_scancode: -Try ScanCode Toolkit +Try ScanCode-Toolkit -------------------- -This section is about using the ScanCode Toolkit, i.e. Performing a scan on a codebase/files to +This section is about using the ScanCode-Toolkit, i.e. Performing a scan on a codebase/files to determine their license, copyrights and other information, according to your requirements. #. The :ref:`newcomer_scan_codebase` section helps you with configuring your virtual environment, @@ -58,13 +58,14 @@ determine their license, copyrights and other information, according to your req Before you start using ScanCode ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -#. You need to make sure :ref:`install_prerequisites` are installed, and a `virtualenv `_ - is created. There are a few different ways to install ScanCode: +#. You need to make sure :ref:`install_prerequisites` are installed. There + are a few different ways to install ScanCode: - :ref:`app_install` [Recommended for newcomers] - :ref:`docker_install` - :ref:`pip_install` - :ref:`source_code_install` +- :ref:`fedora_install` #. Run ``scancode -h`` to make sure ScanCode was installed properly. @@ -90,7 +91,7 @@ Once you are all set up with ScanCode-Toolkit, i.e. Running ``scancode -h`` show #. Refer :ref:`synopsis_quickstart` for commonly used scan commands, and commonly used :ref:`synopsis_output`. (The recommended output format is ``JSON``) -#. Refer `this section `_ for Extractcode Options. +#. Refer :doc:`../rst_snippets/extract` for the use of ExtractCode. #. :ref:`how_to_run_a_scan` is a sample tutorial for absolute beginners, to walk them through the process of running a scan. Follow this tutorial and perform a scan on the ``sample`` folder @@ -142,7 +143,7 @@ ScanCode Versions .. _newcomer_learn_scancode: -Learn more about ScanCode Toolkit +Learn more about ScanCode-Toolkit --------------------------------- Here we give an introduction on the ScanCode-Toolkit Documentation Sections that can help you to @@ -153,7 +154,7 @@ learn more about ScanCode-Toolkit. CLI Reference ^^^^^^^^^^^^^ -This section contains a complete guide to ScanCode Toolkit Command Line options, i.e. What the +This section contains a complete guide to ScanCode-Toolkit Command Line options, i.e. What the command-line options are, how different options affect the scan and outputs, how to use these options and examples of their use cases. @@ -179,7 +180,7 @@ This section has documentation on :ref:`explain_how_scancode_works`. Plugins ^^^^^^^ -Plugins are an integral part of ScanCode Toolkit in the sense they are used to easily extend +Plugins are an integral part of ScanCode-Toolkit in the sense they are used to easily extend ScanCode capabilities, and developers can code their own plugins according to their requirements. This section has documentation on: @@ -215,7 +216,7 @@ If you haven't contributed to ScanCode-Toolkit refer :ref:`newcomer_good_first_i To determine where to contribute, you can refer: -#. ScanCode Toolkit tracks issues via the `GitHub Issue tracker `_ +#. ScanCode-Toolkit tracks issues via the `GitHub Issue tracker `_ #. Broad `milestones `_ for upcoming versions are also maintained. And documentation related to contributing code can be referred at :ref:`contrib_code_dev`. @@ -266,7 +267,7 @@ You can contribute to the following Open Issues on documentation. #. `First Timers Only Issues List `_ #. `Documentation Inconsistencies Tracker `_ -#. `ScanCode Toolkit Documentation Roadmap `_ +#. `ScanCode-Toolkit Documentation Roadmap `_ #. `Issues with label Documentation `_ .. note:: diff --git a/docs/source/how-to-guides/install_new_license_plugin.rst b/docs/source/how-to-guides/install_new_license_plugin.rst index 59bfc9a726..1fc7201771 100644 --- a/docs/source/how-to-guides/install_new_license_plugin.rst +++ b/docs/source/how-to-guides/install_new_license_plugin.rst @@ -40,7 +40,7 @@ Entry points definition in ``setup.py`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ First, in ``setup.py``, you must provide an entry point called ``scancode_location_provider``. -This allows ScanCode Toolkit to discover the plugin and use it in license detection. +This allows ScanCode-Toolkit to discover the plugin and use it in license detection. Here is the definition of ``entry_points`` in ``setup.py``:: entry_points={ @@ -51,7 +51,7 @@ Here is the definition of ``entry_points`` in ``setup.py``:: The ``scancode_location_provider`` entry point maps to a list with information about the plugin. The variable ``licenses_to_install1`` is the name of the entry point. All entry point names -**must** start with the prefix ``licenses``, or else ScanCode Toolkit will not use them in +**must** start with the prefix ``licenses``, or else ScanCode-Toolkit will not use them in license detection. Directory structure diff --git a/docs/source/index.rst b/docs/source/index.rst index 81c474f0fc..0527a2c2ee 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,9 +1,9 @@ -ScanCode Toolkit Documentation +ScanCode-Toolkit Documentation ============================== -Welcome to ScanCode Toolkit Documentation! +Welcome to ScanCode-Toolkit Documentation! -If you are new to ScanCode Toolkit, start here: +If you are new to ScanCode-Toolkit, start here: .. toctree:: :maxdepth: 2 @@ -100,7 +100,7 @@ Reference Documents -------------------- Reference documents provide reference pages for technical reference information -about ScanCode Toolkit, including how it works and supported features. +about ScanCode-Toolkit, including how it works and supported features. .. toctree:: :maxdepth: 2 diff --git a/docs/source/misc/faq.rst b/docs/source/misc/faq.rst index ba6606deb9..7c3c396619 100644 --- a/docs/source/misc/faq.rst +++ b/docs/source/misc/faq.rst @@ -56,12 +56,12 @@ integration with my system to trigger the license check and to use the result? In terms of API, there are two stable entry points: -#. The JSON output when you use it as a command line tool from any language or -when you call the scancode.cli.scancode function from a Python script. +- The JSON output when you use it as a command line tool from any language + or when you call the scancode.cli.scancode function from a Python script. -#. Otherwise the scancode.cli.api module provides a simple function if you are -only interested in calling a certain service on a given file (such as license -detection or copyright detection) +- Otherwise the scancode.cli.api module provides a simple function if you + are only interested in calling a certain service on a given file (such as + license detection or copyright detection) Can I install ScanCode in a Unicode path? diff --git a/docs/source/misc/support.rst b/docs/source/misc/support.rst index 40dee1ba0e..e1781f1b71 100644 --- a/docs/source/misc/support.rst +++ b/docs/source/misc/support.rst @@ -24,5 +24,5 @@ Join the conversation Join our `general chatroom `_ to chat with aboutcode community members, and if you want to talk to users and developers of -ScanCode Toolkit, use `scancode room `_ +ScanCode-Toolkit, use `scancode room `_ diff --git a/docs/source/reference/available_package_parsers.rst b/docs/source/reference/available_package_parsers.rst index bdeacf4924..3fe2cbe706 100644 --- a/docs/source/reference/available_package_parsers.rst +++ b/docs/source/reference/available_package_parsers.rst @@ -5,7 +5,7 @@ Supported package manifests and package datafiles ------------------------------------------------- -Scancode supports a wide variety of package manifests, lockfiles +ScanCode supports a wide variety of package manifests, lockfiles and other package datafiles containing package and dependency information. diff --git a/docs/source/tutorials/how_to_extract_archives.rst b/docs/source/tutorials/how_to_extract_archives.rst index 244a2eeead..2cf1a2f3b6 100644 --- a/docs/source/tutorials/how_to_extract_archives.rst +++ b/docs/source/tutorials/how_to_extract_archives.rst @@ -3,7 +3,7 @@ How To Extract Archives ======================= -ScanCode Toolkit provides archive extraction. This command can be used before running a scan over +ScanCode-Toolkit provides archive extraction. This command can be used before running a scan over a codebase in order to ensure all archives are extracted. Archives found inside an extracted archive are extracted recursively. Extraction is done in-place in a directory and named after the archive with ``'-extract'`` appended. diff --git a/docs/source/tutorials/how_to_set_what_will_be_detected_in_a_scan.rst b/docs/source/tutorials/how_to_set_what_will_be_detected_in_a_scan.rst index c4a73f6856..4c572f04e3 100644 --- a/docs/source/tutorials/how_to_set_what_will_be_detected_in_a_scan.rst +++ b/docs/source/tutorials/how_to_set_what_will_be_detected_in_a_scan.rst @@ -5,7 +5,7 @@ How to set what will be detected in Scan ScanCode allows you to scan a codebase for license, copyright and other interesting information that can be discovered in files. The following options are available for detection when using -ScanCode Toolkit: +ScanCode-Toolkit: .. include:: /rst_snippets/basic_options.rst diff --git a/docs/source/tutorials/how_to_visualize_scan_results.rst b/docs/source/tutorials/how_to_visualize_scan_results.rst index b5b57841f8..97cf774e37 100644 --- a/docs/source/tutorials/how_to_visualize_scan_results.rst +++ b/docs/source/tutorials/how_to_visualize_scan_results.rst @@ -9,7 +9,7 @@ Detailed Installation and Usage guide can be found here - :ref:`scancode-workbe .. WARNING:: - This tutorial uses the 32.x version of ScanCode-Toolkit, and ScanCode Workbench 4.0.x (This version of ScanCode Workbench is compatible with scans from any ScanCode Toolkit develop + This tutorial uses the 32.x version of ScanCode-Toolkit, and ScanCode Workbench 4.0.x (This version of ScanCode Workbench is compatible with scans from any ScanCode-Toolkit develop version/branch at or after v32.x). If you are using an older version of ScanCode-Toolkit, check respective versions of this documentation. Also refer the ScanCode Workbench `release highlights `_.