Merge pull request #1851 from AyanSinhaMahapatra/add-doc-link-to-readme

Add documentation links and update install related guides

Author: pombredanne

CONTRIBUTING.rst

@@ -56,6 +56,7 @@ For other questions, discussions, and chats, we have:
 
 - a mailing list at `sourceforge <https://lists.sourceforge.net/lists/listinfo/aboutcode-discuss>`_
 
+- a Gitter channel to discuss Documentation at https://gitter.im/aboutcode-org/gsod-season-of-docs
 
 Bug reports
 ===========
@@ -77,10 +78,16 @@ When `reporting a bug`__ please include:
 Documentation improvements
 ==========================
 
-Documentation can come in the form of wiki pages, docstrings, blog posts,
-articles, etc. Even a minor typo fix is welcomed. 
-See also extra documentation on the `Wiki <https://github.com/nexB/scancode-toolkit/wiki>`_.
+Documentation can come in the form of new documentation pages/sections, tutorials/how-to documents,
+any other general upgrades, etc. Even a minor typo fix is welcomed. 
 
+If something is missing in the documentation or if you found some part confusing,
+please file an issue with your suggestions for improvement. Use the “Documentation Improvement”
+template. Your help and contributions makes ScanCode docs better, we love hearing from you!
+
+The ScanCode documentation is hosted at `scancode-toolkit.readthedocs.io <https://scancode-toolkit.readthedocs.io/en/latest/>`_.
+
+If you want to contribute to Scancode Dcoumentation, you'll find `this guide here <https://scancode-toolkit.readthedocs.io/en/latest/contribute/contrib_doc.html>`_ helpful.
 
 Development
 ===========

INSTALL.rst

@@ -0,0 +1,64 @@
+============
+Installation
+============
+
+There are 3 main ways you can `install ScanCode <https://scancode-toolkit.readthedocs.io/en/latest/getting-started/install.html>`_.
+
+- Installation as an Application: Downloading Releases (Recommended)
+- Installation as a library: via pip
+- Installation from Source Code: Git Clone
+
+Prerequisites
+-------------
+
+Before installing ScanCode make sure you've installed the prerequisites properly. This mainly
+refers to installing the required Python interpreter (Python 3.6 is recommended).
+
+- For Linux(Ubuntu): ``sudo apt install python3.6-dev bzip2 xz-utils zlib1g libxml2-dev libxslt1-dev``
+- For MacOS: Install Python 3.6.8 from https://www.python.org/ftp/python/3.6.8/python-3.6.8-macosx10.6.pkg
+- For Windows: Install Python 3.6.8 from https://www.python.org/ftp/python/3.6.8/python-3.6.8.exe
+
+Refer `Prerequisites <https://scancode-toolkit.readthedocs.io/en/latest/getting-started/install.html#prerequisites>`_ for detailed information on all different platforms and Python Versions.
+
+Installation as an Application : Downloading Releases
+-----------------------------------------------------
+
+#. Download and extract the latest ScanCode release from https://github.com/nexB/scancode-toolkit/releases/
+
+#. Open a terminal window and then `cd` to the extracted ScanCode directory. 
+
+#. Run this command to self-configure and display the help-text.
+
+    - Linux/Mac : ``./scancode --help``
+    - Windows : ``scancode --help``
+
+Installation as a library: via pip
+----------------------------------
+
+#. Create a Python 3.6 Virtual Environment and activate the same::
+
+    virtualenv -p /usr/bin/python3.6 venv-scancode && source venv-scancode/bin/activate
+
+#. Run ``pip install scancode-toolkit`` 
+
+Installation from Source Code: Git Clone
+----------------------------------------
+
+#. Download the Source Code or Use Git Clone::
+
+    git clone https://github.com/nexB/scancode-toolkit.git
+    cd scancode-toolkit
+
+#. You can jump to any checkpoint/Branch/Commit using the following command::
+
+    git checkout master
+
+#. Run the Configure Script
+
+  - On Linux/Mac: ``./configure``
+  - On Windows: ``configure``
+
+
+Note the `Commands will vary <https://scancode-toolkit.readthedocs.io/en/latest/getting-started/install.html#commands-variation>`_ across different Installation methods and Platforms.
+
+If this displays the `Help Text <https://scancode-toolkit.readthedocs.io/en/latest/cli-reference/help-text-options.html#help-text>`_, you are all set to start using ScanCode.

README.rst

@@ -1,12 +1,15 @@
 ================
 ScanCode toolkit
 ================
+
 A typical software project often reuses hundreds of third-party packages.
 License and origin information is not always easy to find and not normalized:
 ScanCode discovers and normalizes this data for you.
 
+Read more about ScanCode here: `scancode-toolkit.readthedocs.io <https://scancode-toolkit.readthedocs.io/en/latest/>`_.
+
 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**.
@@ -37,8 +40,9 @@ Why use ScanCode?
 
 - ScanCode is heavily **tested** with an automated test suite of over **8000 tests**.
 
-See our roadmap for upcoming features:
-https://github.com/nexB/scancode-toolkit/wiki/Roadmap
+- ScanCode has extensive and updated Documentation help for users.
+
+See our `roadmap <https://scancode-toolkit.readthedocs.io/en/latest/contribute/roadmap.html>`_ for upcoming features.
 
 Build and tests status
 ======================
@@ -51,72 +55,71 @@ Build and tests status
 |Develop| |devel-cov|  | |devel-posix|   | |devel-win|  |
 +-------+--------------+-----------------+--------------+
 
+Documentation Build
+-------------------
 
-Quick Start
-===========
++--------+--------------+
+|Version | **RTD Build**|
++========+==============+
+| Latest | |docs-rtd|   |
++--------+--------------+
 
-Install Python 2.7 then download and extract the latest ScanCode release from
-https://github.com/nexB/scancode-toolkit/releases/ 
 
-Then run ``./scancode -h`` for help.
+Documentation
+=============
 
+The ScanCode documentation is hosted at `scancode-toolkit.readthedocs.io <https://scancode-toolkit.readthedocs.io/en/latest/>`_.
 
-Installation
-============
+If you are new to Scancode, start `here <https://scancode-toolkit.readthedocs.io/en/latest/getting-started/newcomer.html>`_.
 
-Pre-requisites:
+Other Important Documentation Pages:
 
-* On Windows, please follow the `Comprehensive Installation instructions
-  <https://github.com/nexB/scancode-toolkit/wiki/Comprehensive-Installation>`_.
-  Make sure you use Python 2.7 32 bits from
-  https://www.python.org/ftp/python/2.7.15/python-2.7.15.msi
+- 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>`_ and `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_arch.html>`_
+- `FAQ <https://scancode-toolkit.readthedocs.io/en/latest/misc/faq.html>`_
 
-* On macOS, install Python 2.7 from
-  https://www.python.org/ftp/python/2.7.15/python-2.7.15-macosx10.6.pkg
-
-  Next, download and extract the latest ScanCode release from
-  https://github.com/nexB/scancode-toolkit/releases/
-
-* On Linux install the Python 2.7 "devel" and these packages using your
-  distribution package manager:
-
-  * On Ubuntu 14, 16 and 18 use:
-    ``sudo apt-get install python-dev xz-utils zlib1g libxml2-dev libxslt1-dev bzip2``
-
-  * On Debian and Debian-based distros use:
-    ``sudo apt-get install python-dev xz-utils zlib1g libxml2-dev libxslt1-dev libbz2-1.0``
-
-  * On RPM distros use:
-    ``sudo yum install python-devel xz-libs zlib libxml2-devel libxslt-devel bzip2-libs``
+See also https://aboutcode.org for related companion projects and tools.
 
-  * On Fedora 22 and later use:
-    ``sudo dnf install python-devel xz-libs zlib libxml2-devel libxslt-devel bzip2-libs``
 
-* See also the `Comprehensive Installation instructions 
-  <https://github.com/nexB/scancode-toolkit/wiki/Comprehensive-Installation>`_
-  for additional instructions.
+Installation
+============
 
+Before installing ScanCode make sure you've installed the prerequisites properly. This mainly
+refers to installing the required Python interpreter (Python 3.6 is recommended). Refer
+`Prerequisites <https://scancode-toolkit.readthedocs.io/en/latest/getting-started/install.html#prerequisites>`_ for detailed information on all different platforms and Python Versions.
 
-Next, download and extract the latest ScanCode release from
-https://github.com/nexB/scancode-toolkit/releases/
+There are 3 main ways you can `install ScanCode <https://scancode-toolkit.readthedocs.io/en/latest/getting-started/install.html>`_.
 
+- `Installation as an Application: Downloading Releases <https://scancode-toolkit.readthedocs.io/en/latest/getting-started/install.html#installation-as-an-application-downloading-releases>`_ *(Recommended)*
+- `Installation from Source Code: Git Clone <https://scancode-toolkit.readthedocs.io/en/latest/getting-started/install.html#installation-from-source-code-git-clone>`_
+- `Installation as a library: via pip <https://scancode-toolkit.readthedocs.io/en/latest/getting-started/install.html#pip-install>`_
 
-Open a terminal window and then `cd` to the extracted ScanCode directory and run
-this command to display help. ScanCode will self-configure if needed::
+Quick Start
+===========
 
-    ./scancode --help
+Note the `Commands Variation <https://scancode-toolkit.readthedocs.io/en/latest/getting-started/install.html#commands-variation>`_ across Installation methods and Platforms.
 
 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
 
+Refer `How to set what will be detected in Scan <https://scancode-toolkit.readthedocs.io/en/latest/tutorials/how_to_set_what_will_be_detected_in_a_scan.html>`_
+and `How to specify Scancode Output Format <https://scancode-toolkit.readthedocs.io/en/latest/tutorials/how_to_format_scan_output.html>`_ for more information.
+
+You can also refer to `Command Line Options Synopsis <https://scancode-toolkit.readthedocs.io/en/latest/cli-reference/synopsis.html>`_ and an exhaustive List of `All Available Options <https://scancode-toolkit.readthedocs.io/en/latest/cli-reference/list-options.html>`_.
 
 Archive extraction
-===================
+==================
 
 The archives that exist in a codebase must be extracted before running a scan:
 ScanCode does not extract files from tarballs, zip files, etc. as part of the
@@ -126,14 +129,7 @@ the mytar.tar.bz2-extract directory::
 
     ./extractcode mytar.tar.bz2
 
-
-Documentation & FAQ
-===================
-
-https://github.com/nexB/scancode-toolkit/wiki
-
-See also https://aboutcode.org for related companion projects and tools.
-
+Refer `All Extractcode Options <https://scancode-toolkit.readthedocs.io/en/latest/cli-reference/list-options.html#all-extractcode-options>`_ and `How To Extract Archives <https://scancode-toolkit.readthedocs.io/en/latest/tutorials/how_to_extract_archives.html>`_ for more information.
 
 Support
 =======
@@ -151,6 +147,7 @@ For discussions and chats, we have:
   You can use your favorite IRC client or use the web chat at
   https://webchat.freenode.net/
 
+* a Gitter channel to discuss Documentation at https://gitter.im/aboutcode-org/gsod-season-of-docs
 
 Source code and downloads
 =========================
@@ -192,3 +189,7 @@ the third-party code used in ScanCode for more details.
 .. |devel-win| image:: https://ci.appveyor.com/api/projects/status/4webymu0l2ip8utr/branch/develop?png=true
     :target: https://ci.appveyor.com/project/nexB/scancode-toolkit
     :alt: Windows Develop branch tests status
+
+.. |docs-rtd| image:: https://readthedocs.org/projects/scancode-toolkit/badge/?version=latest
+    :target: https://scancode-toolkit.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status

docs/source/cli-reference/synopsis.rst

@@ -18,28 +18,30 @@ Toolkit Command Line Interface in the following sections:
 Installation
 ------------
 
-Scancode-Toolkit installation can be installed from ``pip``, the default Python Package Manager.
-However, there are more ways to perform an installation, and refer the following sections for
+Scancode-Toolkit installation can be done by downloading ScanCode as an application, which
+is recommended generally. For users who wish to use ScanCode as a library, it can be
+installed via ``pip``, the default Python Package Manager. Refer the following sections for
 detailed Instructions on the each of the Installation Methods.
 
+- :ref:`app_install`
 - :ref:`pip_install`
-- :ref:`latest_release_download_install`
-- :ref:`source_configure_install`
+- :ref:`source_code_install`
 
 .. _synopsis_quickstart:
 
 Quickstart
 ----------
 
-The basic command to perform a scan, if Scancode is installed from ``pip``::
+The basic command to perform a scan, in case of a download and configure installation
+(on Linux/MacOS) is::
 
-    scancode [OPTIONS] <OUTPUT FORMAT OPTION(s)> <SCAN INPUT>
+    path/to/scancode [OPTIONS] <OUTPUT FORMAT OPTION(s)> <SCAN INPUT>
 
-The basic usage in case of a download and configure installation (on Linux/MacOS) is::
+The basic usage, if Scancode is installed from ``pip``, or in Windows::
 
-    path/to/scancode [OPTIONS] <OUTPUT FORMAT OPTION(s)> <SCAN INPUT>
+    scancode [OPTIONS] <OUTPUT FORMAT OPTION(s)> <SCAN INPUT>
 
-.. include::  /rst_snippets/tip_snippets/synopsis_quickstart.rst
+.. include::  /rst_snippets/note_snippets/synopsis_install_quickstart.rst
 
 Here Scancode scans the <SCAN INPUT> file or directory for license, origin and packages and saves
 results to FILE(s) using one or more output format option. Error and progress are printed to
@@ -64,10 +66,12 @@ While a scan using absolute paths from the file system root will look like::
     home/ayansm/software/scancode-toolkit-3.1.1/scancode -clpieu --json-pp home/ayansm/scan_scan_results/output.json home/ayansm/codebases/samples/
 
 Commands similar to ``scancode --clpi --json-pp output.json samples`` will be used as examples
-throughout the documentation. Here we are inside the ``virtualenv`` where Scancode-Toolkit was
-installed by ``pip``, and the default ``samples`` folder is being scanned, which is distributed
-by default with Scancode-Toolkit.
+throughout the documentation.
+
+- Here we are inside the ``virtualenv`` where Scancode-Toolkit is configured.
 
+- And the default ``samples`` folder is being scanned, which is distributed by default with
+  Scancode-Toolkit.
 
 .. _scancode_cli_options:
 

docs/source/conf.py

@@ -34,6 +34,7 @@
 # This points to aboutcode.readthedocs.io
 # In case of "undefined label" ERRORS check docs on intersphinx to troubleshoot
 # Link was created at commit - https://github.com/nexB/aboutcode/commit/faea9fcf3248f8f198844fe34d43833224ac4a83
+
 intersphinx_mapping = {'aboutcode': ('https://aboutcode.readthedocs.io/en/latest/', None),
                        'scancode-workbench': ('https://scancode-workbench.readthedocs.io/en/develop/', None)}