Update install doc minimum requirements #2835

Signed-off-by: Philippe Ombredanne <[email protected]>

Author: pombredanne

docs/scripts/doc8_style_check.sh

@@ -2,13 +2,18 @@ Comprehensive Installation
 ==========================
 
 
-There are four main ways to install ScanCode.
+There in one way to install ScanCode.
 
 - :ref:`app_install`
 
     The recommended method is to download the latest application release as an
     application and then configure and use directly. No knowledge of pip/git or
-    other developer tools is necessary.
+    other developer tools is necessary. You only need to install Python then
+    download and extract the ScanCode application archive to run ScanCode.
+    For standard usage that's all you need.
+
+
+For advanced usage and experienced users, you can also use any of these mode:
 
 - :ref:`docker_install`
 
@@ -18,13 +23,14 @@ There are four main ways to install ScanCode.
 
 - :ref:`source_code_install`
 
-    You can clone the git source code repository and then run a configure script
-    to configure and install ScanCode.
+    You can clone the git source code repository and then run the configure script
+    to configure and install ScanCode for local and development usage.
 
 - :ref:`pip_install`
 
     To use ScanCode as a library in your application, you can install it via
-    ``pip``. This is recommended for developers/users familiar with Python.
+    ``pip``. This is recommended for developers or users familiar with Python
+    that want to embed ScanCode as a library.
 
 ----
 
@@ -38,14 +44,15 @@ Before Installing
 System Requirements
 ^^^^^^^^^^^^^^^^^^^
 
-- Hardware : ScanCode will run best with a modern X86 processor and at least 4GB
-  of RAM and 500MB of disk. These are bare minimum requirements.
+- Hardware : ScanCode will run best with a modern X86 64 bits processor and at
+  least 8GB of RAM and 2GB of disk space. These are minimum requirements.
 
 - Supported operating systems: ScanCode should run on these 64-bit OSes running
   X86_64 processors:
 
     #. Linux: on recent 64-bit Linux distributions,
-    #. Mac: on recent 64-bit macOS (10.14 and up),
+    #. Mac: on recent x86 64-bit macOS (10.15 and up, including 11 and 12),
+       Use the X86 emulation mode on Apple ARM M1 CPUs.
     #. Windows: on Windows 10 and up,
     #. FreeBSD,
 
@@ -56,15 +63,15 @@ Prerequisites
 ^^^^^^^^^^^^^
 
 ScanCode needs a Python 3.7+ interpreter; We support all Python versions from
-3.7 to 3.10.
+3.7 to 3.10. The default version for the application archives is Python 3.8
 
 - **On Linux**:
 
     Use your package manager to install ``python3``.
 
     For Ubuntu, it is ``sudo apt install python3-dev``
 
-    - On Ubuntu 14, 16, 18 and 20 run::
+    - On Ubuntu 16, 18, 20 and 22 run::
 
           sudo apt install python-dev bzip2 xz-utils zlib1g libxml2-dev libxslt1-dev libpopt0
 
@@ -84,13 +91,17 @@ ScanCode needs a Python 3.7+ interpreter; We support all Python versions from
     If these packages are not available from your package manager, you must
     compile them  from sources.
 
+
 - **On Mac**:
 
-    Download and install Python 3.7 or higher from https://www.python.org/
+    The default Python 3 provided with macOS is 3.8.
+    Alternativelu you can download and install Python 3.8 from https://www.python.org/
+
+
 
 - **On Windows**:
 
-    Download and install Python 3.7 or higher from https://www.python.org/
+    Download and install Python 3.8 from https://www.python.org/
 
     .. Note::
 
@@ -99,30 +110,32 @@ ScanCode needs a Python 3.7+ interpreter; We support all Python versions from
 
     See the :ref:`windows_app_install` section for more installation details.
 
-.. Note::
-
-    ScanCode app archives come with packaged with all required dependencies except
-    for Python that has to be downloaded and installed separately.
-
 ----
 
 .. _app_install:
 
 Installation as an Application: Downloading Releases
 -----------------------------------------------------
 
+.. Note::
+
+    ScanCode app archives come with packaged with all required dependencies except
+    for Python that has to be downloaded and installed separately.
+
+
+
 Installation on Linux and Mac
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Get the Scancode Toolkit tarball archive of a specific version and your
 operating system by going to the `project releases page <https://github.com/nexB/scancode-toolkit/releases/>`_
 
-For example, Version 21.8.1 archive can be obtained from
-`Toolkit release 21.8.1 <https://github.com/nexB/scancode-toolkit/releases/tag/v21.8.1>`_
+For example, Version 30.0.1 archive can be obtained from
+`Toolkit release 30.0.1 <https://github.com/nexB/scancode-toolkit/releases/tag/v30.0.1>`_
 under assets options. Download the archive for your operating systen and extract
 the archive from command line::
 
-    tar -xvf scancode-toolkit-21.8.1_py39-linux.tar.xz
+    tar -xvf scancode-toolkit-30.0.1_py38-linux.tar.gz
 
 
 Or, on Linux, right click and select "Extract Here".
@@ -177,7 +190,7 @@ Installation on Windows 10
   then Right-click in this window and select Paste. This will paste the path you
   copied before and is where you extracted ScanCode::
 
-    cd path/to/extracted_ScanCode
+    cd path/to/extracted/ScanCode
 
 - Press Enter.
 
@@ -189,8 +202,7 @@ Installation on Windows 10
     scancode -h
 
 - Press enter. This first command will configure your ScanCode installation.
-
-- Several messages are displayed followed by the ScanCode command help.
+  Several messages are displayed followed by the ScanCode command help.
 
 - The installation is complete.
 
@@ -200,7 +212,8 @@ Un-installation
 
 - Delete the directory in which you extracted ScanCode.
 - Delete any temporary files created in your system temp and user temp directory
-  under a scanCode-prefixed directory.
+  under a ScanCode-prefixed directory such as .scancode-tk or .cache/scancode-tk.
+
 
 ----
 
@@ -242,9 +255,9 @@ Display help::
 
     docker run scancode-toolkit --help
 
-Mount current working directory and run scan on mounted folder::
+Mount current working directory and run scan on this mounted folder::
 
-    docker run -v $PWD/:/project scancode-toolkit -clpeui --json-pp /project/result.json /project
+    docker run -v $PWD/:/project scancode-toolkit -clipeu --json-pp /project/result.json /project
 
 This will mount your current working from the host into ``/project`` in the container
 and then scan the contents. The output ``result.json`` will be written back to your
@@ -253,6 +266,7 @@ current working directory on the host.
 Note that the parameters *before* ``scancode-toolkit`` are used for docker,
 those after will be forwarded to scancode.
 
+
 ----
 
 
@@ -261,45 +275,27 @@ those after will be forwarded to scancode.
 Installation from Source Code: Git Clone
 -----------------------------------------
 
-You can also download the Scancode Toolkit Source Code and build from it yourself. This is how you
-would want to do it if:
-
-- You are adding new patches to Scancode and want to test it. So you build ScanCode locally
-  with your added changes.
+You can download the Scancode Toolkit Source Code and build from it yourself.
+This is what you would want to do it if:
 
-- You want to test a specific version/checkpoint/branch from the VCS.
+- You are developing ScanCode or adding new patches or want to run tests.
+- You want to test or run a specific version/checkpoint/branch from the version control.
 
 
 Download the ScanCode-Toolkit Source Code
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you don't have the ScanCode Toolkit Source Code downloaded, get it from its
-`official Repository <https://github.com/nexB/scancode-toolkit/>`_ (Downloaded as a .zip file)
-
-Or you can run the following if you have `Git <https://git-scm.com/>`_ installed::
+Run the following once you have `Git <https://git-scm.com/>`_ installed::
 
     git clone https://github.com/nexB/scancode-toolkit.git
     cd scancode-toolkit
 
-Now, by default the files are checked out to the develop branch, but you can jump to any checkpoint
-using the following command::
-
-    git checkout develop
-
-Here, ``develop`` branch has the latest release of Scancode-Toolkit.
-You can also check out to any of the following:
-
-- Branches (Locally created or already present) [Example - ``develop``]
-- Tags (essentially version numbers) [Example - ``v21.8.1``, ``v21.5.31``]
-- Commits (use the shortened commit hash) [Example - ``4502055``, ``f276398``]
-
 
 Configure the build
 ^^^^^^^^^^^^^^^^^^^
 
-ScanCode use the Configure scripts to install a virtualenv, install required packaged dependencies
-as pip requirements and more configure tasks such that ScanCode can be installed in a
-self-contained way with no network connectivity required.
+ScanCode use a configure scripts to create an isolated virtual environment,
+install required packaged dependencies.
 
 On Linux/Mac:
 
@@ -308,13 +304,15 @@ On Linux/Mac:
 - run ``./configure``
 - run ``source venv/bin/activate``
 
+
 On Windows:
 
 - open a command prompt
 - cd to the clone directory
 - run ``configure``
 - run ``venv\Scripts\activate``
 
+
 Now you are ready to use the freshly configured scancode-toolkit.
 
 .. NOTE::
@@ -331,7 +329,9 @@ Now you are ready to use the freshly configured scancode-toolkit.
 Installation as a library: via ``pip``
 --------------------------------------
 
-ScanCode can be installed using ``pip``, the default Python Package Manager.
+ScanCode can be installed from the public PyPI repository using ``pip`` which
+the standard Python package management tool.
+
 The steps are:
 
 #. Create a Python virtual environment::
@@ -345,10 +345,13 @@ For more information on Python virtualenv, visit this
 
     source venv/bin/activate
 
-#. Run ``pip install --upgrade pip setuptools wheel`` to install the latest
-   versions of base utilities.
+#. Run pip to install the latest versions of base utilities::
+
+    pip install --upgrade pip setuptools wheel
+
+#. Install the latest version of ScanCode::
 
-#. Run ``pip install scancode-toolkit`` to install the latest version of ScanCode.
+    pip install scancode-toolkit
 
 .. NOTE::
 
@@ -357,27 +360,32 @@ For more information on Python virtualenv, visit this
     special use cases such as packaging for a Linux or FreeBSD distro.
 
 
-To uninstall, run ``pip uninstall scancode-toolkit``.
+To uninstall, run::
+
+    pip uninstall scancode-toolkit
 
 
 ----
 
 .. _commands_variation:
 
-Commands Variation
-------------------
+Command Invocation Variations
+-----------------------------
+
+These are the commands to invoke ScanCode based on:
 
-The commands to run ScanCode varies for:
+- your installation methods
+- your operating systems
 
-- Different Installation Methods
-- OS used
+The two form of commands are:
 
-The two types of commands are:
+- Use the scancode command directly, typically on Windows or in an activated virtualenv::
 
-- ``scancode [OPTIONS] <OUTPUT FORMAT OPTION(s)> <SCAN INPUT>``
-- ``path/to/scancode OPTIONS] <OUTPUT FORMAT OPTION(s)> <SCAN INPUT>``
+    scancode [OPTIONS] <OUTPUT FORMAT OPTION(s)> <SCAN INPUT>
 
-In the second case, ``./scancode`` is used if already in the directory.
+- Use a path to the scancode command, typically with an application installation ::
+
+    path/to/scancode [OPTIONS] <OUTPUT FORMAT OPTION(s)> <SCAN INPUT>
 
 These variations are summed up in the following table:
 
@@ -391,23 +399,16 @@ These variations are summed up in the following table:
       - Install from Source Code
 
     * - Linux
-      - `./scancode`
-      - `scancode`
-      - `./scancode`
+      - path: `./scancode`
+      - direct: scancode
+      - path: `./scancode` or direct: `scancode`
 
     * - Mac
-      - `./scancode`
-      - `scancode`
-      - `./scancode`
+      - path: `./scancode`
+      - direct: scancode
+      - path: `./scancode` or direct: `scancode`
 
     * - Windows
-      - `scancode`
-      - `scancode`
-      - `scancode`
-
-To sum it up, ``scancode`` is used in these two cases:
-
-- If ``pip`` install is used.
-- If the OS is Windows.
-
-In all other cases, ``./scancode`` is used.
+      - path: `scancode`
+      - direct: scancode
+      - path: `scancode` or direct: `scancode`