diff --git a/docs/source/conf.py b/docs/source/conf.py index 7ea76f24..7128bbeb 100644 --- a/docs/source/conf.py +++ b/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"] diff --git a/docs/source/definitions.rst b/docs/source/definitions.rst new file mode 100644 index 00000000..8403e1c2 --- /dev/null +++ b/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. diff --git a/docs/source/getting-started/index.rst b/docs/source/getting-started/index.rst index d18f0a21..9616f4ea 100644 --- a/docs/source/getting-started/index.rst +++ b/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 `__. - Once downloaded, you'll find the ScanCode Workbench executable inside the - ``ScanCode Workbench--`` 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 `__. + +- Once downloaded, you'll find the ScanCode Workbench executable inside the ``ScanCode Workbench--`` 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: diff --git a/docs/source/how-to-guides/explore-your-data/navigate-package-explorer.rst b/docs/source/how-to-guides/explore-your-data/navigate-package-explorer.rst index 80c83fa5..4ae72065 100644 --- a/docs/source/how-to-guides/explore-your-data/navigate-package-explorer.rst +++ b/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` diff --git a/docs/source/rst_snippets/refer-pie-charts.rst b/docs/source/rst_snippets/refer-pie-charts.rst index 5ba1a86c..6029fe30 100644 --- a/docs/source/rst_snippets/refer-pie-charts.rst +++ b/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 diff --git a/docs/source/ui-reference/chart-summary-view.rst b/docs/source/ui-reference/chart-summary-view.rst index 6de2e40c..1a358902 100644 --- a/docs/source/ui-reference/chart-summary-view.rst +++ b/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 diff --git a/docs/source/ui-reference/copyright-info-dashboard.rst b/docs/source/ui-reference/copyright-info-dashboard.rst index 490acd65..ff436a18 100644 --- a/docs/source/ui-reference/copyright-info-dashboard.rst +++ b/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 diff --git a/docs/source/ui-reference/data/license-explorer/license-explorer-nav.gif b/docs/source/ui-reference/data/license-explorer/license-explorer-nav.gif index 3a3e7737..d318fb45 100644 Binary files a/docs/source/ui-reference/data/license-explorer/license-explorer-nav.gif and b/docs/source/ui-reference/data/license-explorer/license-explorer-nav.gif differ diff --git a/docs/source/ui-reference/data/package-explorer/package-details.gif b/docs/source/ui-reference/data/package-explorer/package-details.gif new file mode 100644 index 00000000..e19fad23 Binary files /dev/null and b/docs/source/ui-reference/data/package-explorer/package-details.gif differ diff --git a/docs/source/ui-reference/data/package-explorer/package-explorer-details.gif b/docs/source/ui-reference/data/package-explorer/package-explorer-details.gif new file mode 100644 index 00000000..bbc413b3 Binary files /dev/null and b/docs/source/ui-reference/data/package-explorer/package-explorer-details.gif differ diff --git a/docs/source/ui-reference/data/package-explorer/package-explorer-nav.gif b/docs/source/ui-reference/data/package-explorer/package-explorer-nav.gif new file mode 100644 index 00000000..060df57e Binary files /dev/null and b/docs/source/ui-reference/data/package-explorer/package-explorer-nav.gif differ diff --git a/docs/source/ui-reference/data/tableview/tableview-to-license.gif b/docs/source/ui-reference/data/tableview/tableview-to-license.gif new file mode 100644 index 00000000..40ba1128 Binary files /dev/null and b/docs/source/ui-reference/data/tableview/tableview-to-license.gif differ diff --git a/docs/source/ui-reference/data/tableview/tableview-to-package.gif b/docs/source/ui-reference/data/tableview/tableview-to-package.gif new file mode 100644 index 00000000..19e0a683 Binary files /dev/null and b/docs/source/ui-reference/data/tableview/tableview-to-package.gif differ diff --git a/docs/source/ui-reference/dependency-info-dashboard.rst b/docs/source/ui-reference/dependency-info-dashboard.rst index da12353e..d4b2170f 100644 --- a/docs/source/ui-reference/dependency-info-dashboard.rst +++ b/docs/source/ui-reference/dependency-info-dashboard.rst @@ -4,12 +4,12 @@ :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 @@ -17,6 +17,7 @@ Summary of Dependencys: - 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 diff --git a/docs/source/ui-reference/file-info-dashboard.rst b/docs/source/ui-reference/file-info-dashboard.rst index 154c030d..f36f4045 100644 --- a/docs/source/ui-reference/file-info-dashboard.rst +++ b/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 diff --git a/docs/source/ui-reference/license-explorer.rst b/docs/source/ui-reference/license-explorer.rst index 977db7dd..4107831b 100644 --- a/docs/source/ui-reference/license-explorer.rst +++ b/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. diff --git a/docs/source/ui-reference/license-info-dashboard.rst b/docs/source/ui-reference/license-info-dashboard.rst index fc3a5836..80d7e300 100644 --- a/docs/source/ui-reference/license-info-dashboard.rst +++ b/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 diff --git a/docs/source/ui-reference/package-explorer.rst b/docs/source/ui-reference/package-explorer.rst index 8f9b00b6..978a0c18 100644 --- a/docs/source/ui-reference/package-explorer.rst +++ b/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 diff --git a/docs/source/ui-reference/package-info-dashboard.rst b/docs/source/ui-reference/package-info-dashboard.rst index f213b478..cbdb079a 100644 --- a/docs/source/ui-reference/package-info-dashboard.rst +++ b/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 diff --git a/docs/source/ui-reference/table-view.rst b/docs/source/ui-reference/table-view.rst index 32c5c1ab..6dedc01a 100644 --- a/docs/source/ui-reference/table-view.rst +++ b/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 ------------------------