Completed UI references, refer-scans, sct-swb interlinks

Signed-off-by: Omkar Phansopkar <[email protected]>

docs/source/conf.py

@@ -24,7 +24,6 @@
 github_repo = "scancode-workbench"
 github_branch = "update/docs"
 
-
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -53,6 +52,7 @@
     'scancode-toolkit': ('https://scancode-toolkit.readthedocs.io/en/latest/', None),
 }
 
+default_dark_mode = False
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/source/definitions.rst

@@ -0,0 +1 @@
+.. |purl_description| replace:: A package URL is used to identify and locate a software package in a mostly universal and uniform way across programing languages, package managers, packaging conventions, tools, APIs and databases.

docs/source/getting-started/index.rst

@@ -7,14 +7,13 @@
 Download and Install
 =======================
 
--  You can download the latest ScanCode Workbench release for your Windows, OS X or Linux
-   operating system from the `ScanCode Workbench releases page <https://github.com/nexB/scancode-workbench/releases>`__.
-   Once downloaded, you'll find the ScanCode Workbench executable inside the
-   ``ScanCode Workbench-<os>-<arch>`` folder
-   On Windows 10, for example, the executable will be named `ScanCode-Workbench.exe`.
-
+- ScanCode Workbench is available for Windows, macOS and Linux -
+   `ScanCode Workbench releases <https://github.com/nexB/scancode-workbench/releases>`__.
+
+- Once downloaded, you'll find the ScanCode Workbench executable inside the ``ScanCode Workbench-<os>-<arch>`` folder. On Windows 10, for example, the executable will be named `ScanCode-Workbench.exe`.
 
--  Note - For CentOS (or linux distros without the new libstdc++):
+.. Note::
+   For CentOS (or linux distros without the new libstdc++), follow these steps:
 
    -  Install the new libstdc++ library:
 

docs/source/how-to-guides/explore-your-data/navigate-package-explorer.rst

@@ -2,9 +2,13 @@
 :index:`How-To: Navigate the Package Explorer View`
 ====================================================
 
+.. include:: ../definitions.rst
+
 Display the Package Explorer view
 ===================================
 
+Packages are uniquely identified using PURLs. ||purl_description|
+
 Once you have a SQLite file loaded into ScanCode Workbench,
 
 * Click on `Package Explorer` in the sidebar or open the :kbd:`View` menu and select :kbd:`Package Explorer`
@@ -41,4 +45,4 @@ You can click on the :kbd:`Data file path` to see that file in the TableView
 .. figure:: data/package-explorer-deps.gif
 
 
-For entire UI reference, Read :ref:`package-explorer` 
+For entire UI reference, See :ref:`package-explorer` 

docs/source/rst_snippets/refer-pie-charts.rst

@@ -1,2 +1,2 @@
 .. note::
-    Refer :ref:`pie-charts` for chart specific features.
+    Refer :ref:`pie-charts` for UI features in charts

docs/source/ui-reference/chart-summary-view.rst

@@ -16,7 +16,4 @@ in the scanned codebase.
 
 .. image:: data/chart-summary-view.gif
 
-.. refer-scans:: Refer these scans
-         :items: item1, item2, item3
-
 .. include:: ../rst_snippets/scans-used.rst

docs/source/ui-reference/copyright-info-dashboard.rst

@@ -4,19 +4,25 @@
 :index:`Copyright Info Dashboard`
 ===================================
 
-Scan must have ``--license`` option for License Info Dashboard
+License info dashboard summarizes the license information detected in scan for files under the selected path.
+Scan must have ``--license`` option for License Info Dashboard.
 
 Summary of Licenses:
 
-- Count of
-    - Unique holders
-    - Unique notices
-    - Unique authors
+- Unique holders
+    No. of unique copyright holders detected.
+- Unique notices
+    No. of unique copyright notices detected.
+- Unique authors
+    No. of unique copyright authors detected.
 
 - Pie charts
     - Copyright Holders
+        Distribution of unique copyright holders indicating the number of files in which each copyright holder was detected.
     - Copyright Notices
+        Distribution of unique copyright notices indicating the number of files in which each copyright notice was detected.
     - Copyright Authors
+        Distribution of unique copyright authors indicating the number of files in which copyrights were authored by each author.
 
 .. include::  /rst_snippets/refer-pie-charts.rst
 

docs/source/ui-reference/dependency-info-dashboard.rst

@@ -4,19 +4,20 @@
 :index:`Dependency Info Dashboard`
 =====================================
 
+Dependency info dashboard summarizes the dependencies information detected in scan for files under the selected path.
 Scan must have ``--package`` option for Dependency Info Dashboard
 
 Summary of Dependencys:
 
-- Count of
-    - Dependencies
+- Total number of Dependencies detected
 
 - Summary table
     - Dependencies per Scope (Runtime, Optional, Resolved) for each Package Type
 
 - Pie charts
     - Dependencies for each Package type
     - Data source IDs
+        Distribution of Unique data source IDs. eg. ``maven_pom``, ``pipfile_lock``, etc
     - Runtime dependencies
     - Resolved dependencies
     - Optional dependencies

docs/source/ui-reference/file-info-dashboard.rst

@@ -4,14 +4,13 @@
 :index:`File Info Dashboard`
 ============================
 
-Scan must have ``--info`` option for File Info Dashboard
+File Info Dashboard summarizes the file information in scan for the selected path. It is a good starting point to understand the file types and programming languages used in the project.
+Scan must have ``--info`` option enabled for the data required in File Info Dashboard.
 
 Summary of files:
 
-- Count of
-    - Files
-    - Directories.
-
+- Total number of Files (under the selected path)
+- Total number of Directories (under the selected path)
 - Pie charts
     - Programming languages
     - File Types

docs/source/ui-reference/license-explorer.rst

@@ -18,11 +18,11 @@ User can scroll through the licenses and select particular license to see detail
 - License Detections
 - License Clues
 
+User can search for a particular license using the search bar at the top.
 These sections' height & navigation pane's width can be adjusted as per convenience.
 
 .. image:: data/license-explorer/license-explorer.gif
 
-
 License Details Pane
 ------------------------------------------
 User can see detailed information of the license selected in the navigation pane.

docs/source/ui-reference/license-info-dashboard.rst

@@ -4,19 +4,25 @@
 :index:`License Info Dashboard`
 ================================
 
-Scan must have ``--license`` option for License Info Dashboard
+License info dashboard summarizes the license information detected for files in the scan under the selected path. It is a good starting point to understand the declaration of licenses in the project.
+Scan must have ``--license`` option enabled for the data required in License Info Dashboard.
 
 Summary of Licenses:
 
-- Count of
-    - Licenses (No. of unique licenses)
-    - Files (No. of files having at least one license)
-    - SPDX Licenses (No. of unique SPDX licenses)
+- Licenses
+    No. of unique licenses detected.
+- Files
+    No. of files (under the selected path) having at least one license detected.
+- SPDX Licenses
+    No. of unique SPDX detected.
 
 - Pie charts
     - License expressions
+        Distribution of unique license expressions indicating the number of files in which each license expression is detected.
     - License keys
+        Distribution of unique license keys indicating the number of files in which each license key is detected.
     - License policies
+        Distribution of unique license policies indicating the number of files in which each license policy is detected.
 
 .. include::  /rst_snippets/refer-pie-charts.rst
 

docs/source/ui-reference/package-explorer.rst

@@ -4,6 +4,8 @@
 :index:`Package Explorer`
 ============================
 
+.. include:: ../definitions.rst
+
 Details of all the Packages & dependencies as well as files in which they were detected can be viewed using the Package Explorer.
 
 Refer - :doc:`scancode-toolkit:reference/available_package_parsers`.
@@ -17,7 +19,14 @@ Packages and dependencies are organised in a hierarchical structure as shown bel
   > ``Package (PURL)``
     > ``Dependencies``
 
-The navigation pane's width can be adjusted as per convenience.
+User can select different filters:
+
+- Data sources - ``maven_pom``, ``go_mod``, ``npm_package_lock_json``, etc
+- Dependency flags - ``Runtime``, ``Resolved``, ``Optional``
+
+  Tip - You can click on the tag on the right side of the dependency to toggle that flag
+
+The navigation pane's width can also be adjusted as per convenience.
 
 .. image:: data/package-explorer/package-explorer-nav.gif
 
@@ -27,7 +36,9 @@ Package Details
 
 User can see following information of the selected package:
 
-- ``Title of details pane`` - PURL of the selected package
+- ``Title of details pane``- PURL
+
+  |purl_description|
 - ``Type``
 - ``Namespace``
 - ``Name``
@@ -41,15 +52,21 @@ User can see following information of the selected package:
 - ``Other license expression SPDX``
 - ``Homepage URL``
 
+***************************
 Datafile paths
-
+***************************
 List of paths of datafiles in which the selected package/dependency was detected.
 User can click on the datafile paths to open that path in the Tableview the match details resulting the selected license 
 
+***************************
 Dependencies table
+***************************
 
 User can see all the dependencies of the selected package in the table, with following details:
+
 - ``Purl``
+
+  |purl_description|
 - ``Scope``
 - ``Resolved``
 - ``Runtime``
@@ -58,8 +75,7 @@ User can see all the dependencies of the selected package in the table, with fol
 - ``Data file``
 - ``Extracted requirement``
 
-@TODO - Gif for package details
-
+.. image:: data/package-explorer/package-details.gif
 
 Dependency Details
 --------------------
@@ -72,6 +88,8 @@ User can see following information of the selected dependency:
 - ``Data file`` - Clickable datafile path to open the datafile in the Tableview
 - ``Data source ID``
 
+The Data file property is a clickable link that opens the Tableview with that file selected.
+
 .. image:: data/package-explorer/dependency-details.png
 
 .. include:: ../rst_snippets/scans-used.rst

docs/source/ui-reference/package-info-dashboard.rst

@@ -4,18 +4,21 @@
 :index:`Package Info Dashboard`
 ===================================
 
+Package info dashboard summarizes the packages detected for files in the scan under the selected path.
 Scan must have ``--package`` option for License Info Dashboard
 
 Summary of Packages:
 
-- Count of
-    - Packages
+- Total number of packages detected
 
 - Pie charts
     - Package Types
+        Distribution of unique package types detected. eg. ``npm``, ``cargo``, ``pypi``, etc.
     - Package Languages
+        Distribution of unique package languages detected. eg. ``Javascript``, ``Python``, ``Ruby``, etc.
     - Package Licenses
-
+        Distribution of unique package licenses detected.
+
 .. include::  /rst_snippets/refer-pie-charts.rst
 
 .. image:: data/package-info/package-info.png

docs/source/ui-reference/table-view.rst

@@ -11,8 +11,11 @@ file size, etc) and package information (package type, primary language of packa
 detected.
 
 The columns can be sorted as well as shown or hidden based on what the user’s
-preferences. Searching for specific clues (license names, copyrights, etc.) is also available in
-this view.
+preferences or using preset groups. Searching for specific clues (license names, copyrights, etc.) is also available in this view.
+
+.. Note::
+  The data in tableview is only available if corresponding options were enabled when performing the scan.
+  Refer - :doc:`scancode-toolkit:cli-reference/list-options`.
 
 ----------------
 Column groups
@@ -109,6 +112,19 @@ Use the ``Search`` bar in the top-right corner to perform searches within the sp
 
 .. image:: data/tableview/tableview-search.gif
 
+Go to License Explorer
+------------------------
+User can go to specific licenses in the licenses explorer by the clickable links in ``License Detections`` column (Grouped under `License cols`). This will open the license explorer with the target license selected.
+Similarly, ``Path`` column in the File regions table in license details pane also provide links which navigate back to the Table view with that File path selected
+
+.. image:: data/tableview/tableview-to-license.gif
+
+Go to Package Explorer
+------------------------
+User can go to specific package in the package explorer by the clickable links in ``For Packages`` column (Grouped under `Package cols`). This will open the package explorer with the target package selected.
+Similarly, Datafile paths in package/dependency details pane as well as dependency table also provide links which navigate back to the Table view with that File path selected
+
+.. image:: data/tableview/tableview-to-package.gif
 
 Pagination
 ------------------------