diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 66854356305..f4c48850050 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -56,6 +56,7 @@ For other questions, discussions, and chats, we have: - a mailing list at `sourceforge `_ +- 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 `_. +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 `_. + +If you want to contribute to Scancode Dcoumentation, you'll find `this guide here `_ helpful. Development =========== diff --git a/INSTALL.rst b/INSTALL.rst new file mode 100644 index 00000000000..d892a59818c --- /dev/null +++ b/INSTALL.rst @@ -0,0 +1,64 @@ +============ +Installation +============ + +There are 3 main ways you can `install ScanCode `_. + +- 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 `_ 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 `_ across different Installation methods and Platforms. + +If this displays the `Help Text `_, you are all set to start using ScanCode. \ No newline at end of file diff --git a/README.rst b/README.rst index 2abb84315a2..3109b02caee 100644 --- a/README.rst +++ b/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 `_. + 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 `_ 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 `_. -Installation -============ +If you are new to Scancode, start `here `_. -Pre-requisites: +Other Important Documentation Pages: -* On Windows, please follow the `Comprehensive Installation instructions - `_. - 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 `_ of ScanCode Command Line Options +- Tutorials on `How to Run a Scan `_ and `How to Visualize Scan results `_ +- An exhaustive List of `All Available Options `_ +- Documentation on `Contributing to Code Development `_ +- Documentation on `Plugin Architecture `_ +- `FAQ `_ -* 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 - `_ - 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 `_ 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 `_. +- `Installation as an Application: Downloading Releases `_ *(Recommended)* +- `Installation from Source Code: Git Clone `_ +- `Installation as a library: via pip `_ -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 `_ 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 `_ 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 `_ +and `How to specify Scancode Output Format `_ for more information. + +You can also refer to `Command Line Options Synopsis `_ and an exhaustive List of `All Available Options `_. 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 `_ and `How To Extract Archives `_ 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 diff --git a/docs/source/cli-reference/synopsis.rst b/docs/source/cli-reference/synopsis.rst index 7608473d742..c6c6a9e26af 100644 --- a/docs/source/cli-reference/synopsis.rst +++ b/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] + path/to/scancode [OPTIONS] -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] + scancode [OPTIONS] -.. include:: /rst_snippets/tip_snippets/synopsis_quickstart.rst +.. include:: /rst_snippets/note_snippets/synopsis_install_quickstart.rst Here Scancode scans the 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: diff --git a/docs/source/conf.py b/docs/source/conf.py index ee0e9da5d13..b869afa112b 100644 --- a/docs/source/conf.py +++ b/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)} diff --git a/docs/source/getting-started/install.rst b/docs/source/getting-started/install.rst index 5ee32c74597..bc8ba137c5c 100644 --- a/docs/source/getting-started/install.rst +++ b/docs/source/getting-started/install.rst @@ -1,30 +1,31 @@ Comprehensive Installation ========================== -The fastest way to install Scancode-Toolkit is by using ``pip``. You can also install -ScanCode-Toolkit by compiling it from source or by Downloading and Configuring the -latest release from GitHub. +There are 3 main ways you can install ScanCode. -- :ref:`pip_install` -- :ref:`latest_release_download_install` -- :ref:`source_configure_install` +- :ref:`app_install` -.. NOTE:: + The recommended method for installing ScanCode is Downloading the latest release as an + application and then configure and use directly. This is easy because no knowledge of pip/git + or other developer tools is necessary. - After ``pip install``, you can perform a scan using only:: +- :ref:`source_code_install` - scancode [OPTIONS] + You can download/clone the source code repository via git/GitHub and then run a configure script + to install ScanCode. - This is unlike other install methods where path to scancode is provided by using - ``path/to/scancode``, or by using ``./scancode`` inside the Scancode install directory. +- :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 Package managers/virtualenv. + +---- Before Installing ----------------- ScanCode requires either Python 3.6.x or Python 2.7.x and is tested on Linux, Mac, and Windows. -Make sure Python 2.7 or Python 3.6 is installed first. +Make sure Python 3.6 or Python 2.7 is installed first. System Requirements ^^^^^^^^^^^^^^^^^^^ @@ -44,86 +45,82 @@ System Requirements Prerequisites ^^^^^^^^^^^^^ -ScanCode needs a Python 3.6 or a Python 2.7 interpreter. +ScanCode needs a Python 3.6 (*highly recommended*) or a Python 2.7 interpreter. .. Note:: - ScanCode currently doesn't support Python 3.7.x, though support will be added soon. + ScanCode currently doesn't support versions above Python 3.6.x, though support will be added soon. -- On Linux: Use your package manager to install ``python2.7`` or ``python3.6``. If they are not - available from your package manager, you must compile it from sources. For instance, visit - https://github.com/dejacode/about-code-tool/wiki/BuildingPython27OnCentos6 for instructions - to compile Python 2.7 from sources on Centos. +- **On Linux**: -- On Ubuntu 12.04, 14.04 and 16.04, you will need to install these packages first: - ``python-dev bzip2 xz-utils zlib1g libxml2-dev libxslt1-dev`` + Use your package manager to install ``python3.6`` (*Recommended*) or ``python2.7``. -- On Debian and Debian-based distros you will need to install these packages first: - ``python-dev libbz2-1.0 xz-utils zlib1g libxml2-dev libxslt1-dev`` + For ubuntu, it is ``sudo apt install python3.6-dev`` -- On RPM-based distros, you will need to install these packages first: - ``python-devel zlib bzip2-libs xz-libs libxml2-devel libxslt-devel`` + - On Ubuntu 14, 16 and 18, run: + ``sudo apt install python3.6-dev bzip2 xz-utils zlib1g libxml2-dev libxslt1-dev`` -- **On Windows**: + - On Debian and Debian-based distros run: + ``sudo apt-get install python3.6-dev libbz2-1.0 xz-utils zlib1g libxml2-dev libxslt1-dev`` - Use the Python 2.7 32-bit (e.g. The Windows x86 MSI installer) for X86 regardless of whether - you run Windows on 32-bit or 64-bit. DO NOT USE Python X86_64 installer even if you run 64 bit - Windows. Download Python from this url: - https://www.python.org/ftp/python/2.7.13/python-2.7.13.msi + - On RPM-based distros run: + ``sudo yum install python3.6-devel zlib bzip2-libs xz-libs libxml2-devel libxslt-devel`` - Install Python on the c: drive and use all default installer options (scancode will try to find - python just in c:\python27\python.exe). See the Windows installation section for more - installation details. + - On Fedora 22 and later run: + ``sudo dnf install python3.6-devel xz-libs zlib libxml2-devel libxslt-devel bzip2-libs`` -.. Note:: - - 64-bit Python interpreters (x86) are currently not supported by Scancode for Python 2.7 in - Windows. Use 32-bit Python isntead, even with 64-bit Windows. + If they are not available from your package manager, you must compile it from sources. + For instance, visit this `wiki `_ + for instructions to compile Python 2.7 from sources on Centos. -- On Mac: Download and install Python from this url: - https://www.python.org/ftp/python/2.7.13/python-2.7.13-macosx10.6.pkg - -.. WARNING:: + To install Python 2.7 instead, replace ``python3.6-dev`` with ``python-dev`` (or ``devel``) + according to your specific platform. - Do not use Unicode, non-ASCII in your installation Path if you are using a Python 2.7 interpreter. +- **On Mac**: ---- + Download and install Python from this url: -.. _pip_install: + - Python 3.6.8 (*recommended*): https://www.python.org/ftp/python/3.6.8/python-3.6.8-macosx10.6.pkg + - Python 2.7.17 : https://www.python.org/ftp/python/2.7.17/python-2.7.17-macosx10.6.pkg -Installation by ``pip`` ------------------------ +- **On Windows**: -Scancode Toolkit can be easily installed using ``pip``. The steps are: + Download and install Python from this url: -#. Create a Python 2.7 or Python 3.6 Virtual Environment:: + - Python 3.6.8 (*recommended*): https://www.python.org/ftp/python/3.6.8/python-3.6.8.exe - virtualenv -p /usr/bin/python3.6 venv-scancode + Add python to PATH, as ScanCode uses the python from PATH. The last Python you install + registers itself in the environment is the default, if you select the "Add to PATH" option + while installing. -#. Activate the Virtual Environment you just created:: + - Python 2.7.17 : https://www.python.org/ftp/python/2.7.17/python-2.7.17.msi - source venv-scancode/bin/activate + Install Python on the c: drive and use all default installer options (ScanCode will try to + find python just in c:python27python.exe). -#. Run ``pip install scancode-toolkit`` to Install Scancode. + .. Note:: -.. NOTE:: + 64-bit Python interpreters (x86-64) are currently not supported by Scancode for Python 3.6/2.7 + in Windows. Use 32-bit Python instead, even with 64-bit Windows. For Python 2.7, use the + 32 bit MSI installer linked above. - If you use Python 2.7, scancode-toolkit Version 3.0.2 is installed by default. For Python 3 - the latest version of Scancode Toolkit is installed by default. + See the :ref:`windows_app_install` section for more installation details. .. WARNING:: - Requesting a specific version through ``pip install`` for Python 3 will give Errors if the - Version isn't 3.1.x or later. + Do not use Unicode, non-ASCII in your installation Path if you are using a Python 2.7 interpreter. + +.. Note:: -To uninstall, run ``pip uninstall scancode-toolkit``. + ScanCode comes with packaged with all dependencies, and so apart from downloading it as an + application, only Python has to be downloaded and installed separately. ---- +---- -.. _latest_release_download_install: +.. _app_install: -Download and Configure latest Release -------------------------------------- +Installation as an Application: Downloading Releases +---------------------------------------------------- Installation on Linux and Mac ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -143,7 +140,7 @@ For ``.tar.bz2`` archive:: tar -xvf scancode-toolkit-3.1.1.tar.bz2 -Or Right Click and select "Extract Here". +Or, Right Click and select "Extract Here". Check whether the :ref:`install_prerequisites` are installed. Open a terminal in the extracted directory and run:: @@ -152,6 +149,8 @@ directory and run:: This will configure ScanCode and display the command line :ref:`cli_help_text`. +.. _windows_app_install: + Installation on Windows ^^^^^^^^^^^^^^^^^^^^^^^ @@ -191,12 +190,10 @@ Installation on Windows - A new 'cmd.exe' window ('Command Prompt' on Windows 10) pops up. -- In this window (aka a 'command prompt'), type the following (i.e., 'cd' followed by a space):: - - cd +- In this window (aka a 'command prompt'), type 'cd' followed by a space and then Right-click in + this window and select Paste. This will paste the path where you extracted ScanCode:: -- Right-click in this window and select Paste. - This will paste the path where you extracted ScanCode. + cd path/to/extracted_ScanCode - Press Enter. @@ -209,35 +206,54 @@ Installation on Windows - Press enter. This 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. +This uses the default Python present in the PATH environment variable i.e. the last Python +installed registers itself in the environment is the default. You can also use the ``configure`` +script to explicitly provide the Python path to ScanCode. + +- Follow the Instructions above till changing the current location of your command prompt to the + root directory where ScanCode is installed. + +- Run this command with the path to Python Executable:: + + configure --python path/to/python + +- You can also use ``path`` instead of ``path/to/python`` to use the python from PATH environment + variable. More information is available at the `configure `_ script (L6-L15). + +- Now you can run ``scancode -h`` to display the Help Text, and here the installation is complete. + Un-installation ^^^^^^^^^^^^^^^ - Delete the directory in which you extracted ScanCode. - Delete any temporary files created in your system temp directory under a ScanCode directory. ---- +---- -.. _source_configure_install: +.. _source_code_install: -Build From Source ------------------ +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. -- You want to test a specific Version/Checkpoint/Branch from the VCS +- You are Adding new patches to Scancode and want to test it. So you build ScanCode locally + with your added changes. +- You want to test a specific Version/Checkpoint/Branch from the VCS. Download the ScanCode-Toolkit Source Code ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you don't have the ScanCode Toolkit Source Code downloaded, get it from it's official Repository -(Downloaded as a .zip file) or run the following:: +If you don't have the ScanCode Toolkit Source Code downloaded, get it from its +`official Repository `_ (Downloaded as a .zip file) + +Or you can run the following if you have `Git `_ installed:: git clone https://github.com/nexB/scancode-toolkit.git cd scancode-toolkit @@ -250,7 +266,7 @@ using the following command:: Here, ``master`` branch has the latest release of Scancode-Toolkit. You can also check out to any of the following: -- Branches (Locally created or already present) +- Branches (Locally created or already present) [Example - ``master``, ``develop`` etc] - Tags (essentially Version Numbers) [Example - ``v3.1.1``, ``v3.1.0`` etc] - Commits (use the shortened commit hash) [Example - ``4502055``, ``f276398`` etc] @@ -261,12 +277,101 @@ ScanCode use the Configure scripts to install a virtualenv, install required pac as pip requirements and more configure tasks such that ScanCode can be installed in a self-contained way with no network connectivity required. -Open a terminal, clone the scancode-toolkit repository, cd to the clone directory and run:: +On Linux/Mac: - ./configure +- Open a terminal +- cd to the clone directory +- run ``./configure`` -On Windows open a command prompt, cd to the clone directory and run instead:: +On Windows: - configure +- open a command prompt +- cd to the clone directory +- run instead ``configure`` Now you are ready to use the freshly configured scancode-toolkit. + +---- + +.. _pip_install: + +Installation as a library: via ``pip`` +-------------------------------------- + +ScanCode can be installed using ``pip``, the default Python Package Manager. The steps are: + +#. Create a Python 3.6 Virtual Environment:: + + virtualenv -p /usr/bin/python3.6 venv-scancode + +For more information on Python virtualenv, visit this `page `_. + +#. Activate the Virtual Environment you just created:: + + source venv-scancode/bin/activate + +#. Run ``pip install scancode-toolkit`` to install the latest version of Scancode. + +.. NOTE:: + + If you use Python 2.7, scancode-toolkit Version 3.0.2 is installed by default. For Python 3 + the latest version of Scancode Toolkit is installed by default. Requesting a specific version + through ``pip install`` for Python 3 will give Errors if the Version isn't 3.1.x or later. + +.. WARNING:: + + Python 3.7.x and 3.8.x is not supported yet. + +To uninstall, run ``pip uninstall scancode-toolkit``. + +---- + +.. _commands_variation: + +Commands Variation +------------------ + +The commands to run ScanCode varies for: + +- Different Installation Methods +- OS used + +The two types of commands are: + +- ``scancode [OPTIONS] `` +- ``path/to/scancode OPTIONS] `` + +In the second case, ``./scancode`` is used if already in the directory. + +These variations are summed up in the following table: + +.. list-table:: + :widths: 10 5 10 50 + :header-rows: 1 + + * - Installation Methods + - Application Install + - Pip Install + - Install from Source Code + + * - Linux + - `./scancode` + - `scancode` + - `./scancode` + + * - Mac + - `./scancode` + - `scancode` + - `./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. diff --git a/docs/source/getting-started/newcomer.rst b/docs/source/getting-started/newcomer.rst index ec537ec4b7f..85c43c04e5f 100644 --- a/docs/source/getting-started/newcomer.rst +++ b/docs/source/getting-started/newcomer.rst @@ -1,3 +1,5 @@ +.. _new_to_scancode: + Are you new to Scancode-Toolkit? ================================ @@ -12,8 +14,9 @@ Table of Contents #. :ref:`newcomer_try_scancode` - :ref:`newcomer_before` + - :ref:`newcomer_install` - :ref:`newcomer_scan_codebase` - - :ref:`newcomer_use_scancode_better` + - :ref:`newcomer_scancode_tips` - :ref:`newcomer_all_tutorials` - :ref:`newcomer_whats_new` @@ -42,15 +45,34 @@ Try ScanCode Toolkit 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, +#. The :ref:`newcomer_scan_codebase` section helps you with configuring your virtual environment, installing Scancode and performing a basic scan, and subsequently visualize the results. -#. The :ref:`newcomer_use_scancode_better` section helps you customize the scan according to your +#. The :ref:`newcomer_scancode_tips` section helps you customize the scan according to your requirements, and better understand the advanced features you can use. #. The :ref:`newcomer_all_tutorials` is essentially an exhaustive list of all Tutorials and How To's with a brief description on what they help you to achieve. +.. _newcomer_install: + +Installing ScanCode +------------------- + +Scancode-Toolkit can be installed in 3 different methods. + +.. include:: /rst_snippets/note_snippets/synopsis_install_quickstart.rst + +#. The :ref:`newcomer_scan_codebase` section helps you with configuring your virtual environment, + installing Scancode and performing a basic scan, and subsequently visualize the results. + +#. The :ref:`newcomer_scancode_tips` section helps you customize the scan according to your + requirements, and better understand the advanced features you can use. + +#. The :ref:`newcomer_all_tutorials` is essentially an exhaustive list of all Tutorials and + How To's with a brief description. + + .. _newcomer_before: Before you start using Scancode @@ -59,10 +81,14 @@ Before you start using Scancode #. You need to make sure :ref:`install_prerequisites` are installed, and a `virtualenv `_ is created. -#. Now you can either run ``pip install scancode-toolkit`` like that in the - :ref:`pip_install` documentation, or follow the instructions for the - :ref:`latest_release_download_install` method. Alternatively, you can also - :ref:`source_configure_install`. +:ref:`app_install` +:ref:`pip_install` +:ref:`source_code_install` + + +#. Now you can either follow the instructions for the recommended :ref:`app_install` method , + or run ``pip install scancode-toolkit`` like that in the :ref:`pip_install` documentation. + Alternatively, you can also :ref:`source_code_install`. #. Run ``scancode -h`` to make sure Scancode was installed properly. If this shows any Error, refer the `Common Installation Errors Issue `_ @@ -94,7 +120,7 @@ Once you are all set up with Scancode Toolkit, i.e. Running ``scancode -h`` show `Scancode Workbench `_. Follow this tutorial :ref:`how_to_visualize_scan_results` to visualize the scan results. -.. _newcomer_use_scancode_better: +.. _newcomer_scancode_tips: Use ScanCode Better ^^^^^^^^^^^^^^^^^^^ @@ -130,7 +156,7 @@ ScanCode Versions #. Refer :ref:`whats_new_this_release` to know more about the latest release. #. You can also refer the `CHANGELOG `_ for more information on specific releases. #. If you want to use/test a specific version of Scancode Toolkit, you can follow the instructions - in :ref:`source_configure_install` docs. + in :ref:`source_code_install` docs. ---- diff --git a/docs/source/getting-started/whats-new.rst b/docs/source/getting-started/whats-new.rst index e847af3c824..e92f865a0d4 100644 --- a/docs/source/getting-started/whats-new.rst +++ b/docs/source/getting-started/whats-new.rst @@ -9,7 +9,7 @@ Quick Summary ------------- - Version - 3.1.1 -- Tag - "v.3.1.1" +- Tag - ``v.3.1.1`` - Date - 5th September 2019 - Type - Pre-Release - Comments - Release v3.1.1 which the release candidate 2 of 3.1.x @@ -55,13 +55,6 @@ deprecated hereafter. The new documentation has improved support in terms of: This results in a much better documentation experience in Users and even contributors. -``pip install`` Support -^^^^^^^^^^^^^^^^^^^^^^^ - -Now, ``pip install`` is the recommended install method, across all platforms. This greatly -simplifies the install process, and is much faster and easier than the Download and Configure -method, for non-developer users. - Python 3 Support ^^^^^^^^^^^^^^^^ @@ -69,3 +62,12 @@ Python 3 is now officially supported by Scancode-Toolkit. This also means improved Unicode support, so it's easy to translate strings from Unicode to other languages. And as Scancode has users in more than 100 languages, this is a major improvement. + +Better install Support +^^^^^^^^^^^^^^^^^^^^^^^ + +Now, Downloading ScanCode as an Application is the recommended install method, across all +platforms. This greatly simplifies the install process, and is much easier for all users. +Developers familiar with package managers can also download ScanCode as a library, via ``pip`` +or configure from the source. All these methods are properly documented, across all platforms +and scenarios. diff --git a/docs/source/index.rst b/docs/source/index.rst index 6990118a1fb..9d21d4b23e4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,21 +1,23 @@ ScanCode Toolkit Documentation ============================== -Guide ------ +Welcome to ScanCode Toolkit Documentation! + +If you are new to ScanCode Toolkit, start here: .. toctree:: :maxdepth: 2 - getting-started/index - cli-reference/index - plugins/index - tutorials/index - how-to-guides/index - explanations/index - contribute/index - misc/index - license + getting-started/newcomer + +Here's a list of more Documentation Pages: + +- A :ref:`cli_synopsis` of ScanCode Command Line Options +- Tutorials on :ref:`how_to_run_a_scan` and :ref:`how_to_visualize_scan_results` +- An exhaustive List of :ref:`cli_list_options` +- Documentation on :ref:`contrib_code_dev` +- Documentation on :ref:`plugin_arch` +- :ref:`faq` ---- @@ -25,12 +27,24 @@ Getting Started .. toctree:: :maxdepth: 2 - getting-started/newcomer + getting-started/index ---- -Tutorial Documents ------------------- +Command Line Options Reference +------------------------------ + +Reference documents describe the Command Line options, and application concepts in depth. + +.. toctree:: + :maxdepth: 2 + + cli-reference/index + +---- + +Tutorials +--------- Tutorial documents provide specific instructions to help you get started. @@ -53,18 +67,36 @@ How-To documents explain how to accomplish specific tasks. ---- -Reference Documents -------------------- +Contribute To ScanCode +---------------------- -Reference documents describe the Command Line options, and application concepts in depth. +.. toctree:: + :maxdepth: 2 + + contribute/index + +---- + +Plugins Documentation +--------------------- .. toctree:: :maxdepth: 2 - cli-reference/index + plugins/index ---- +Miscellaneous Documents +----------------------- + +.. toctree:: + :maxdepth: 2 + + misc/index + license + + Discussion Documents -------------------- diff --git a/docs/source/rst_snippets/note_snippets/synopsis_install_quickstart.rst b/docs/source/rst_snippets/note_snippets/synopsis_install_quickstart.rst index dd6f0cabd3a..ca2100df38e 100644 --- a/docs/source/rst_snippets/note_snippets/synopsis_install_quickstart.rst +++ b/docs/source/rst_snippets/note_snippets/synopsis_install_quickstart.rst @@ -1,4 +1,15 @@ .. note:: - For more information on the Scan Command for Various Installation Methods/Operating Systems, - refer :ref:`syn_install`. + Please note that different for different install methods, scan commands vary. + + The basic command to perform a scan, in case of a download and configure installation + (on Linux/MacOS) is:: + + path/to/scancode [OPTIONS] + + The basic usage, if Scancode is installed from ``pip``, or in Windows:: + + scancode [OPTIONS] + + For more information on how the Scan Command varies for Various Installation + Methods/Operating Systems, refer :ref:`commands_variation`. diff --git a/docs/source/rst_snippets/tip_snippets/synopsis_quickstart.rst b/docs/source/rst_snippets/tip_snippets/synopsis_quickstart.rst deleted file mode 100644 index 3656acc7065..00000000000 --- a/docs/source/rst_snippets/tip_snippets/synopsis_quickstart.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. Tip:: - - On Windows use ``scancode`` instead of ``path/to/scancode``, irrespective of - the installation method.