Merge pull request #4667 from aboutcode-org/new-readme to restructure the README

Restructure the README for clarity

Author: DennisClark

README.rst

@@ -1,23 +1,28 @@
 ================
-ScanCode toolkit
+ScanCode Toolkit
 ================
 
-A typical software project often reuses hundreds of third-party packages.
-License and packages, dependencies and origin information is not always easy to
-find and not normalized: ScanCode discovers and normalizes this data for you.
+ScanCode Toolkit is a set of code scanning tools that detect the origin (copyrights), license and vulnerabilities of code, packages and dependencies in a codebase. ScanCode Toolkit is an `AboutCode project <https://aboutcode.org>`_.
 
-Read more about ScanCode here: https://scancode-toolkit.readthedocs.io/.
+Why Use ScanCode Toolkit?
+=========================
+
+ScanCode Toolkit is the leading tool in scanning depth and accuracy, used by hundreds of software teams. You can use ScanCode Toolkit as a command line tool or as a library.
 
-Check out the code at https://github.com/nexB/scancode-toolkit
+Getting Started
+===============
 
-Discover also:
+Instructions to get you up and running on your local machine are at `Getting Started <https://scancode-toolkit.readthedocs.io/en/stable/getting-started/index.html>`_
 
-- The ScanCode.io server project here: https://scancodeio.readthedocs.io
-- The ScanCode Workbench project for visualization of scancode results data:
-  https://github.com/nexB/scancode-workbench
-- Other companion SCA projects for code origin, license and security analysis
-  here: https://aboutcode.org
+The ScanCode Toolkit documentation also provides:
 
+- prerequisites for installing the software.
+- instructions guiding you to start scanning code.
+- a comprehensive guide to the command line options.
+- tutorials that provide hands-on guidance to ScanCode features.
+- how to expand ScanCode Licenses and Detection Rules with your own data.
+- how to generate Attribution from a ScanCode scan.
+- guidelines for contributing to code development.
 
 Build and tests status
 ======================
@@ -31,13 +36,10 @@ compabitility with multiple versions of Windows, Linux and macOS.
 |  |azure|   | |docs-rtd|   |  |docs-github-actions|  |  |release-github-actions|  |
 +------------+--------------+-------------------------+----------------------------+
 
+Benefits of ScanCode
+====================
 
-Why use ScanCode?
-=================
-
-- As a **standalone command-line tool**, ScanCode is **easy to install**, run,
-  and embed in your CI/CD processing pipeline.
-  It runs on **Windows, macOS, and Linux**.
+- ScanCode is heavily **tested** with an automated test suite of over **30,000 tests**.
 
 - ScanCode is **used by several projects and organizations** such as
   the `Eclipse Foundation <https://www.eclipse.org>`_,
@@ -49,6 +51,14 @@ Why use ScanCode?
   `RedHat Fabric8 analytics <https://github.com/fabric8-analytics>`_,
   and many more.
 
+- You can also organize and run ScanCode server-side with the
+  companion `ScanCode.io web app <https://github.com/aboutcode-org/scancode.io>`_
+  to organize and store multiple scan projects including scripted scanning pipelines.
+
+- As a **standalone command-line tool**, ScanCode is **easy to install**, run,
+  and embed in your CI/CD processing pipeline.
+  It runs on **Windows, macOS, and Linux**.
+
 - ScanCode detects licenses, copyrights, package manifests, direct dependencies,
   and more both in **source code** and **binary** files and is considered as the
   best-in-class and reference tool in this domain, re-used as the core tools for
@@ -66,187 +76,32 @@ Why use ScanCode?
 - You can save your scan results as **JSON, YAML, HTML, CycloneDX or SPDX** or
   even create your own format with Jinja templates.
 
-- You can also organize and run ScanCode server-side with the
-  companion `ScanCode.io web app <https://github.com/nexB/scancode.io>`_
-  to organize and store multiple scan projects including scripted scanning pipelines.
-
-- ScanCode output data can be easily visualized and analysed using the
-  `ScanCode Workbench <https://github.com/nexB/scancode-workbench>`_ desktop app.
-
-- ScanCode is **actively maintained**, has a **growing users and contributors
-  community**.
-
-- ScanCode is heavily **tested** with an automated test suite of over **20,000 tests**.
-
-- ScanCode has an extensive and growing documentation.
-
 - ScanCode can process packages, build manifest and lockfile formats to collect
-  Package URLs and extract metadata: Alpine packages, BUCK files, ABOUT files,
-  Android apps, Autotools, Bazel, JavaScript Bower, Java Axis, MS Cab,
-  Rust Cargo, Cocoapods, Chef Chrome apps, PHP Composer and composer.lock,
-  Conda, CPAN, Debian, Apple dmg, Java EAR, WAR, JAR, FreeBSD packages,
-  Rubygems gemspec, Gemfile and Gemfile.lock, Go modules, Haxe packages,
-  InstallShield installers, iOS apps, ISO images, Apache IVY, JBoss Sar,
-  R CRAN, Apache Maven, Meteor, Mozilla extensions, MSI installers,
-  JavaScript npm packages, package-lock.json, yarn.lock, NSIS Installers,
-  NuGet, OPam, Cocoapods, Python PyPI setup.py, setup.cfg, and
-  several related lockfile formats, semi structured README
-  files such as README.android, README.chromium, README.facebook, README.google,
-  README.thirdparty, RPMs, Shell Archives, Squashfs images, Java WAR, Windows
-  executables and the Windows registry
-  and a few more. See `all available package parsers <https://scancode-toolkit.readthedocs.io/en/stable/reference/available_package_parsers.html>`_
+  Package URLs and extract metadata. See all available `package parsers
+  <https://scancode-toolkit.readthedocs.io/en/stable/reference/index.html>`_
   for the exhaustive list.
 
-See our `roadmap <https://scancode-toolkit.readthedocs.io/en/latest/contribute/roadmap.html>`_
-for upcoming features.
-
-
-Documentation
-=============
-
-The ScanCode documentation is hosted at
-`scancode-toolkit.readthedocs.io <https://scancode-toolkit.readthedocs.io/en/latest/>`_.
-
-If you are new to visualization of scancode results data, start with our
-`newcomer <https://scancode-toolkit.readthedocs.io/en/latest/getting-started/newcomer.html>`_ page.
-
-If you want to compare output changes between different versions of ScanCode,
-or want to look at scans generated by ScanCode, review our
-`reference scans <https://github.com/nexB/scancode-toolkit-reference-scans>`_.
-
-Other Important Documentation Pages:
-
-- A `synopsis <https://scancode-toolkit.readthedocs.io/en/latest/cli-reference/synopsis.html>`_
-  of ScanCode command line options.
-
-- Tutorials on:
-
-  - `How to run a scan <https://scancode-toolkit.readthedocs.io/en/latest/tutorials/how_to_run_a_scan.html>`_
-  - `How to visualize scan results <https://scancode-toolkit.readthedocs.io/en/latest/tutorials/how_to_visualize_scan_results.html>`_
-
-- An exhaustive list of `all available options <https://scancode-toolkit.readthedocs.io/en/latest/cli-reference/list-options.html>`_
-
-- Documentation on `Contributing to Code Development <https://scancode-toolkit.readthedocs.io/en/latest/contribute/contrib_dev.html>`_
-
-- Documentation on `Plugin Architecture <https://scancode-toolkit.readthedocs.io/en/latest/plugins/plugin-architecture.html>`_
-
-- `FAQ <https://scancode-toolkit.readthedocs.io/en/latest/misc/faq.html>`_
-
-See also https://aboutcode.org for related companion projects and tools.
-
-
-Installation
-============
-
-Before installing ScanCode make sure that you have installed the prerequisites
-properly. This means installing Python 3.13 for x86/64 architectures.
-We support Python 3.10, 3.11, 3.12 and 3.13.
-
-See `prerequisites <https://scancode-toolkit.readthedocs.io/en/latest/getting-started/install.html#prerequisites>`_
-for detailed information on the support platforms and Python versions.
-
-There are a few common ways to `install ScanCode <https://scancode-toolkit.readthedocs.io/en/latest/getting-started/install.html>`_.
-
-- `**Installation as an application: Install Python 3.13, download a release archive, extract and run**.
-  <https://scancode-toolkit.readthedocs.io/en/latest/getting-started/install.html#installation-as-an-application-downloading-releases>`_
-  This is the recommended installation method.
-
-- `Development installation from source code using a git clone
-  <https://scancode-toolkit.readthedocs.io/en/latest/getting-started/install.html#installation-from-source-code-git-clone>`_
-
-- `Development installation as a library with "pip install scancode-toolkit"
-  <https://scancode-toolkit.readthedocs.io/en/latest/getting-started/install.html#pip-install>`_
-  [Note that this is not supported on arm64 machines]
-
-- `Run in a Docker container with a git clone and "docker run"
-  <https://scancode-toolkit.readthedocs.io/en/latest/getting-started/install.html#installation-using-docker>`_
-
-- In Fedora 40+ you can `dnf install scancode-toolkit`
-
-
-Quick Start
-===========
-
-After ScanCode is installed successfully you can run an example scan printed on screen as JSON::
-
-    scancode -clip --json-pp - samples
-
-Follow the `How to Run a Scan <https://scancode-toolkit.readthedocs.io/en/latest/tutorials/how_to_run_a_scan.html>`_
-tutorial to perform a basic scan on the ``samples`` directory distributed by
-default with ScanCode.
-
-See more command examples::
-
-    scancode --examples
-
-See `How to select what will be detected in a scan
-<https://scancode-toolkit.readthedocs.io/en/latest/tutorials/how_to_set_what_will_be_detected_in_a_scan.html>`_
-and `How to specify the output format <https://scancode-toolkit.readthedocs.io/en/latest/tutorials/how_to_format_scan_output.html>`_
-for more information.
-
-You can also refer to the `command line options synopsis
-<https://scancode-toolkit.readthedocs.io/en/latest/cli-reference/synopsis.html>`_
-and an exhaustive list of `all available command line options
-<https://scancode-toolkit.readthedocs.io/en/latest/cli-reference/list-options.html>`_.
-
-
-Archive extraction
-==================
-
-By default ScanCode does not extract files from tarballs, zip files, and
-other archives as part of the scan. The archives that exist in a codebase
-must be extracted before running a scan: `extractcode` is a bundled utility
-behaving as a mostly-universal archive extractor. For example, this command will
-recursively extract the mytar.tar.bz2 tarball in the mytar.tar.bz2-extract
-directory::
-
-    ./extractcode mytar.tar.bz2
-
-See `all extractcode options <https://scancode-toolkit.readthedocs.io/en/latest/reference/cli-extractcode.html>`_
-and `how to extract archives <https://scancode-toolkit.readthedocs.io/en/latest/tutorials/how_to_extract_archives.html>`_ for details.
-
-
 Support
 =======
 
-If you have a problem, a suggestion or found a bug, please enter a ticket at:
-https://github.com/nexB/scancode-toolkit/issues
+If you have a specific problem, suggestion or bug, please submit a 
+`GitHub issue <https://github.com/aboutcode-org/scancode-toolkit/issues>`_.
 
-For discussions and chats, we have:
+For quick questions or socializing, join the AboutCode community discussions on `Slack <https://join.slack.com/t/aboutcode-org/shared_invite/zt-3li3bfs78-mmtKG0Qhv~G2dSlNCZW2pA>`_.
 
-* an official Gitter channel for `web-based chats
-  <https://matrix.to/#/#aboutcode-org_discuss:gitter.im>`_.
-  Gitter is now accessible through `Element <https://element.io/download>`_
-  or an `IRC bridge <https://matrix-org.github.io/matrix-appservice-irc/latest/usage.html>`_.
-  There are other AboutCode project-specific channels available there too.
-
-* The discussion channel for `scancode <https://matrix.to/#/#aboutcode-org_scancode:gitter.im>`_
-  specifically aimed at users and developers using scancode-toolkit.
-
-Source code and downloads
-=========================
-
-* https://github.com/aboutcode-org/scancode-toolkit/releases
-* https://github.com/aboutcode-org/scancode-toolkit.git
-* https://pypi.org/project/scancode-toolkit/
-* https://github.com/aboutcode-org/scancode-thirdparty-src.git
-* https://github.com/aboutcode-org/scancode-plugins.git
-* https://github.com/aboutcode-org/thirdparty-packages.git
+Interested in commercial suppport? Contact the `AboutCode team <mailto:[email protected]>`_.
 
 License
 =======
 
-* Apache-2.0 as the overall license
-* CC-BY-4.0 for reference datasets (initially was in the Public Domain).
-* Multiple other secondary permissive or copyleft licenses (LGPL, MIT,
+* `Apache-2.0 <apache-2.0.LICENSE>`_ is the overall license.
+* `CC-BY-4.0 <cc-by-4.0.LICENSE>`_ applies to reference datasets.
+* There are multiple secondary permissive or copyleft licenses (LGPL, MIT,
   BSD, GPL 2/3, etc.) for third-party components and test suite code and data.
 
-
-See the NOTICE file and the .ABOUT files that document the origin and license of
+See the `NOTICE file <NOTICE>`_ and the `.ABOUT files <https://github.com/search?q=repo%3Aaboutcode-org%2Fscancode-toolkit+path%3A*.ABOUT&type=code>`_ that document the origin and license of
 the third-party code used in ScanCode for more details.
 
-
-
 .. |azure| image:: https://dev.azure.com/nexB/scancode-toolkit/_apis/build/status/nexB.scancode-toolkit?branchName=develop
     :target: https://dev.azure.com/nexB/scancode-toolkit/_build/latest?definitionId=1&branchName=develop
     :alt: Azure tests status (Linux, macOS, Windows)
@@ -265,7 +120,7 @@ the third-party code used in ScanCode for more details.
 
 
 Acknowledgements, Funding, Support and Sponsoring
---------------------------------------------------------
+=================================================
 
 This project is funded, supported and sponsored by:
 
@@ -394,3 +249,5 @@ Communications Networks, Content and Technology under grant agreement No 1010695
     :target: https://nlnet.nl/discovery/
     :height: 40
     :alt: NGI Discovery logo
+
+**End of ScanCode Toolkit README**