Fix documentation issues (#4457)

chinyeungli · AyanSinhaMahapatra · web-flow · commit 166b616890f2 · 2025-07-04T20:16:25.000+05:30
* Fixed #4434 - Changed "Scancode" to "ScanCode" * Fixed #4446 - Corrected non-clickable link * Fixed #4444 - Remove the duplicated installation content * Fixed #4445 - Added reference links to the TOC and the Scan Output Options page within the 'Output Formats' section. * Fixed #4443 - Added wording to clarify the differences between `--json` and `--json-pp` * Fixed #4440 - Added reference for "Git" under the "Installation via Docker" section * Update "ScanCode Toolkit" to "ScanCode-Toolkit" * Corrected typo * Fixed #4437 - Remove the needed for virtualenv * Fixed #2485 - Fixed the format in the integration section. * Correct CI Documentation check * Fixed #1330 - Update doc to reference `--license-text` is not compatiable with `--csv` output * Restore install references to synopsis Signed-off-by: Chin Yeung Li <tli@nexb.com> Signed-off-by: Ayan Sinha Mahapatra <ayansmahapatra@gmail.com> Co-authored-by: Ayan Sinha Mahapatra <ayansmahapatra@gmail.com>
diff --git 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
@@ -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
@@ -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
@@ -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 <cli_extract>`
@@ -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
@@ -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
@@ -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 <https://github.com/aboutcode-org/scancode-toolkit/releases/>`_
 
 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 <https://docs.docker.com/engine/install/>`_.
 
 
 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 <https://git-scm.com/>`_ installed::
+
+    git clone https://github.com/aboutcode-org/scancode-toolkit.git
 
 
 Build the Docker image
@@ -328,7 +329,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
@@ -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 <https://docs.python-guide.org/dev/virtualenvs/>`_
-   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 <file:///home/ayansm/Desktop/GSoD/main_repo/aboutcode/docs/build/html/scancode-toolkit/cli-reference/list-options.html#all-extractcode-options>`_ 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 <https://github.com/aboutcode-org/scancode-toolkit/issues>`_
+#. ScanCode-Toolkit tracks issues via the `GitHub Issue tracker <https://github.com/aboutcode-org/scancode-toolkit/issues>`_
 #. Broad `milestones <https://github.com/aboutcode-org/scancode-toolkit/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 <https://github.com/aboutcode-org/scancode-toolkit/issues/1826>`_
 #. `Documentation Inconsistencies Tracker <https://github.com/aboutcode-org/scancode-toolkit/issues/1813>`_
-#. `ScanCode Toolkit Documentation Roadmap <https://github.com/aboutcode-org/scancode-toolkit/issues/1824>`_
+#. `ScanCode-Toolkit Documentation Roadmap <https://github.com/aboutcode-org/scancode-toolkit/issues/1824>`_
 #. `Issues with label Documentation <https://github.com/aboutcode-org/scancode-toolkit/issues?q=is%3Aopen+is%3Aissue+label%3Adocumentation>`_
 
 .. 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
@@ -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
@@ -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
@@ -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
@@ -24,5 +24,5 @@ Join the conversation
 
 Join our `general chatroom <https://matrix.to/#/#aboutcode-org_discuss:gitter.im>`_ to chat
 with aboutcode community members, and if you want to talk to users and developers of
-ScanCode Toolkit, use `scancode room <https://matrix.to/#/#aboutcode-org_scancode:gitter.im>`_
+ScanCode-Toolkit, use `scancode room <https://matrix.to/#/#aboutcode-org_scancode:gitter.im>`_
 
diff --git 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
@@ -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
@@ -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
@@ -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 <https://github.com/aboutcode-org/scancode-workbench/releases/>`_.
