Merge pull request #628 from nexB/docs/license-review-todos-newui

Updated illustrations corresponding to new UI for to-do, reviews, matches table
aboutcode-org · Feb 14, 2024 · c019c2f · c019c2f
2 parents 461135f + 3f55592
commit c019c2f
Show file tree

Hide file tree

Showing 32 changed files with 139 additions and 64 deletions.
diff --git a/.husky/pre-commit b/.husky/pre-commit
@@ -2,3 +2,4 @@
 . "$(dirname -- "$0")/_/husky.sh"
 
 npm test
+cd docs && ./scripts/doc8_style_check.sh && ./scripts/sphinx_build_link_check.sh
diff --git a/Release.md b/Release.md
@@ -5,9 +5,11 @@
 - Build filetree with missing directories to support `--only-findings` scans by @OmkarPh #624
 - Sort the files in tableview by their depth in directory tree by @OmkarPh in #625
 
+### Note - Due to new features & schema changes, you'll have to re-import scans in workbench, previously generated sqlite files aren't compatible with this and further releases
+
 ## ScanCode Toolkit Compatibility
 
-This v4.0.0 of ScanCode Workbench is compatible with scans from any [ScanCode Toolkit](https://github.com/nexB/scancode-toolkit/) releases at or after [`v32.0.0`](https://github.com/nexB/scancode-toolkit/releases/tag/v32.0.0rc4) and also from the latest develop, but using the latest `v32.x` stable releases is recommended: [latest SCTK release](https://github.com/nexB/scancode-toolkit/releases/latest).
+This v4.0.1 of ScanCode Workbench is compatible with scans from any [ScanCode Toolkit](https://github.com/nexB/scancode-toolkit/) releases at or after [`v32.0.0`](https://github.com/nexB/scancode-toolkit/releases/tag/v32.0.0rc4) and also from the latest develop, but using the latest `v32.x` stable releases is recommended: [latest SCTK release](https://github.com/nexB/scancode-toolkit/releases/latest).
 
 ## Bug fixes
 
@@ -25,4 +27,4 @@ This v4.0.0 of ScanCode Workbench is compatible with scans from any [ScanCode To
 
 # New Contributors
 
-- @dotarjun made his first contribution in #615
+- @dotarjun made his first contribution in #615
diff --git a/attribution.html b/attribution.html
@@ -25,25 +25,25 @@
   </head>
 
   <body>
-    <h1>Attribution for ScanCode Workbench 4.0.0 by nexB</h1>
+    <h1>Attribution for ScanCode Workbench 4.0.1 by nexB</h1>
 
     <p>
       For instructions on how to obtain a copy of any source code being made
       publicly available by nexB Inc. related to software used in ScanCode
       Workbench you may send your request in writing to:<br /><br />
       nexB Inc.<br />
     </p>
-    <p>735 Industrial Road #101<br />San Carlos, CA 94070<br />USA</p>
+    <p>4966 El Camino Real, Suite 119,<br />Los Altos, CA 94022<br />USA</p>
     <p></p>
     <p>
       Contact:
       <a href="http://www.nexb.com/" rel="nofollow">http://www.nexb.com/</a>
     </p>
 
-    <h2>About ScanCode Workbench 4.0.0:</h2>
+    <h2>About ScanCode Workbench 4.0.1:</h2>
 
     <p>
-      ScanCode Workbench 4.0.0 is licensed under
+      ScanCode Workbench 4.0.1 is licensed under
       <a href="#license_apache-2.0">Apache 2.0</a> AND
       <a href="#license_mit">MIT License</a> AND
       <a href="#license_cc0-1.0">CC0-1.0</a> AND
@@ -86,7 +86,7 @@ <h2>About ScanCode Workbench 4.0.0:</h2>
   You may also contact us to request the source code by email at [email protected] or
   by postal mail at:
     nexB Inc., ScanCode Workbench open source code request
-    735 Industrial Road, Suite #101, 94070 San Carlos, CA, USA
+    4966 El Camino Real, Suite 119, Los Altos, CA 94022, USA
   Please indicate in your communication the ScanCode Workbench version for which you are
   requesting source code.
 

diff --git a/docs/Makefile b/docs/Makefile
@@ -20,6 +20,7 @@ docs:
 	@echo
 	@echo "Starting up the docs server..."
 	@echo
+	make clean
 	$(SPHINXAUTOBUILD) --port 8000 --watch ${SOURCEDIR} $(SOURCEDIR) "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
 
 # Catch-all target: route all unknown targets to Sphinx using the new

diff --git a/docs/README.md b/docs/README.md
@@ -4,7 +4,7 @@ The first step you want to do is create the python virtual environment:
 
 ```
 $ cd docs/
-$ python3 -m venv venv
+$ python -m venv venv
 $ source venv/bin/activate
 $ pip install -r requirements.txt
 ```

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -7,3 +7,4 @@ doc8>=0.11.2
 jinja2
 markupSafe
 sphinx-copybutton
+sphinx_rtd_dark_mode
diff --git a/docs/source/_static/favicon.ico b/docs/source/_static/favicon.ico
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -22,7 +22,8 @@
 author = 'nexB Inc. and others'
 github_user = "nexB"
 github_repo = "scancode-workbench"
-github_branch = "update/docs"
+github_branch = "develop"
+html_favicon = '_static/favicon.ico'
 
 # -- General configuration ---------------------------------------------------
 
@@ -36,6 +37,7 @@
     "sphinx_reredirects",
     "sphinx.ext.extlinks",
     "sphinx_copybutton",
+    "sphinx.ext.autosectionlabel",
 ]
 
 
@@ -85,7 +87,7 @@
     "conf_py_path": "/docs/source/",  # path in the checkout to the docs root
 }
 
-html_css_files = ["_static/theme_overrides.css"]
+html_css_files = ["theme_overrides.css"]
 
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
@@ -115,6 +117,11 @@
     'scan_samples': (f"https://github.com/{github_user}/{github_repo}/blob/{github_branch}/samples/%s", '%s'),
 }
 
+# Ignore following links in linkcheck
+linkcheck_ignore = [
+    'https://matrix.to/#/#aboutcode-org_discuss:gitter.im'
+]
+
 # -- Options for LaTeX output -------------------------------------------------
 
 latex_elements = {

diff --git a/docs/source/contribute/building.rst b/docs/source/contribute/building.rst
@@ -100,7 +100,7 @@ Create python environment, make docs
    cd docs/
 
    # Setup virtual environment for python dependencies
-   python3 -m venv venv
+   python -m venv venv
    source venv/bin/activate
 
    # Install dependencies

diff --git a/docs/source/getting-started/index.rst b/docs/source/getting-started/index.rst
@@ -14,7 +14,7 @@ Download and Install
    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`.
+   On Windows 10, for example, the executable will be named `ScanCode-Workbench-4.0.1.exe`.
 
 .. include:: ../rst_snippets/centos-note.rst
 

diff --git a/docs/source/how-to-guides/explore-your-data/data/license-explorer-fileregion.gif b/docs/source/how-to-guides/explore-your-data/data/license-explorer-fileregion.gif
diff --git a/docs/source/how-to-guides/explore-your-data/data/license-explorer-review.gif b/docs/source/how-to-guides/explore-your-data/data/license-explorer-review.gif
diff --git a/docs/source/how-to-guides/explore-your-data/data/license-explorer-search.gif b/docs/source/how-to-guides/explore-your-data/data/license-explorer-search.gif
diff --git a/docs/source/how-to-guides/explore-your-data/data/license-explorer-select.gif b/docs/source/how-to-guides/explore-your-data/data/license-explorer-select.gif
diff --git a/docs/source/how-to-guides/explore-your-data/data/license-explorer-table.gif b/docs/source/how-to-guides/explore-your-data/data/license-explorer-table.gif
diff --git a/docs/source/how-to-guides/explore-your-data/navigate-license-explorer.rst b/docs/source/how-to-guides/explore-your-data/navigate-license-explorer.rst
@@ -11,30 +11,46 @@ Click on `License Explorer` in the sidebar or open the :kbd:`View` menu
 and select :kbd:`License Explorer`
 
 
-Select a License
-=========================
+Select and search for a License
+==================================
 
 On the left pane, Licenses are shown in two categories: `License Detections` & `License clues`.
 You can select any of these licenses & more detailed information about
 that license will be reflected on the right
 
 .. figure:: data/license-explorer-select.gif
 
-Search Licenses
-====================
+.. figure:: data/license-explorer-search.gif
 
-You can search for any license detecttion / clue by typing in the search box on the top-left
 
-.. figure:: data/license-explorer-search.gif
+Review licenses
+===========================================
+
+When reviewing large number of licenses over multiple sessions,
+You can tick the checkbox beside any of theselicense detections or clues to
+mark them as reviewed or unreviewed so that you can continue from where you left off.
+
+Based on this review status, you can filter the licenses using filter options on the top
+
+.. figure:: data/license-explorer-review.gif
+
 
 Matches & File regions table
 ===================================
 
-For the selected license, you can view the matches resulting into the
+For the selected license, you can view the details of matches resulting into the
 detection and the file regions where the license was detected.
-You can click on the data file path to view that path in Tableview
 
-.. figure:: data/license-explorer-table.gif
+In the file regions table, You can click on the data file path to view that path in Tableview.
+Similarly, detection origin is a clickable icon. It determines the source of detection.
+
+- Package icon indicates that the detection belongs to a package manifest,
+  you can click on it to view the source package manifest in :ref:`package-explorer`.
+
+- File icon indicates that the detection belongs to a plain file,
+  you can click on it to view the file in :ref:`table-view`.
+
+.. figure:: data/license-explorer-fileregion.gif
 
 For entire UI reference, Read :ref:`license-explorer`
 

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
@@ -37,7 +37,7 @@ dependency flags by selecting filter values in the top-left
 
 .. figure:: data/package-explorer-filter.gif
 
-Dependencies table
+Dependencies
 ========================
 
 When a package is selected, the dependencies for that package are shown

diff --git a/docs/source/ui-reference/chart-summary-view.rst b/docs/source/ui-reference/chart-summary-view.rst
@@ -14,6 +14,6 @@ selected by clicking the dropdown at the top of the view. The chart displays the
 values for the selected directory tree node and attribute and the number of times each value occurs
 in the scanned codebase.
 
-.. image:: data/chart-summary-view.gif
+.. figure:: data/chart-summary-view.gif
 
 .. include:: ../rst_snippets/scans-used.rst
diff --git a/docs/source/ui-reference/data/license-explorer/license-explorer-fileregion.gif b/docs/source/ui-reference/data/license-explorer/license-explorer-fileregion.gif
diff --git a/docs/source/ui-reference/data/license-explorer/license-explorer-matchedtext.gif b/docs/source/ui-reference/data/license-explorer/license-explorer-matchedtext.gif
diff --git a/docs/source/ui-reference/data/license-explorer/license-explorer-matches.gif b/docs/source/ui-reference/data/license-explorer/license-explorer-matches.gif
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
diff --git a/docs/source/ui-reference/data/license-explorer/license-explorer-review.gif b/docs/source/ui-reference/data/license-explorer/license-explorer-review.gif
diff --git a/docs/source/ui-reference/data/license-explorer/license-explorer-search.gif b/docs/source/ui-reference/data/license-explorer/license-explorer-search.gif
diff --git a/docs/source/ui-reference/data/license-explorer/license-explorer-select.gif b/docs/source/ui-reference/data/license-explorer/license-explorer-select.gif
diff --git a/docs/source/ui-reference/data/license-explorer/license-explorer-todos.png b/docs/source/ui-reference/data/license-explorer/license-explorer-todos.png
diff --git a/docs/source/ui-reference/directory-tree.rst b/docs/source/ui-reference/directory-tree.rst
@@ -13,10 +13,10 @@ Similarly, if a single file is selected, only information for that selected file
 Demo of filetree on different views:
 ------------------------------------------------
 
-.. image:: data/directory-tree/directory-tree-navigate.gif
+.. figure:: data/directory-tree/directory-tree-navigate.gif
 
-.. image:: data/directory-tree/directory-tree-copyright.gif
+.. figure:: data/directory-tree/directory-tree-copyright.gif
 
-.. image:: data/directory-tree/directory-tree-chartview.gif
+.. figure:: data/directory-tree/directory-tree-chartview.gif
 
 .. include:: ../rst_snippets/scans-used.rst
diff --git a/docs/source/ui-reference/license-explorer.rst b/docs/source/ui-reference/license-explorer.rst
@@ -10,57 +10,102 @@ were detected can be viewed using the License Explorer.
 Refer -
 :doc:`scancode-toolkit:reference/license-detection-reference`
 
-.. @TODO - Replace with anchored link after merging docs PR inScanCode Toolkit
-.. :doc:`scancode-toolkit:reference/license-detection-reference#what-is-a-licensedetection`
-
 License Navigation Pane
 -------------------------------
 User can scroll through the licenses and select particular license to see
 detailed information in the License details pane. Licenses are divided into two sections:
+
 - 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
+.. figure:: data/license-explorer/license-explorer-select.gif
+
+
+Search Licenses
+====================
+
+You can search for any license detecttion / clue by typing in the search box on the top-left
+
+.. figure:: data/license-explorer/license-explorer-search.gif
+
+
+Filter & Mark Licenses as Reviewed / Unreviewed
+===================================================
+
+When reviewing large number of licenses over multiple sessions,
+You can tick the checkbox beside any of theselicense detections or clues to
+mark them as reviewed or unreviewed so that you can continue from where you left off.
+
+Based on this review status, you can filter the licenses using filter options on the top
+
+.. figure:: data/license-explorer/license-explorer-review.gif
+
 
 License Details Pane
 ------------------------------------------
-User can see detailed information of the license selected in the navigation pane.
-Title of details pane - License Expression
-Instances - No. of times license is detected
-Score - Clue's confidence about the license (Shown only for clues)
+For the selected license, you can view the details of matches resulting into the
+detection and the file regions where the license was detected.
+
+- Title of details pane - License Expression
+- Instances - No. of times license is detected
+- Score - Clue's confidence about the license (Shown only for clues)
+
 
-Matches Table:
+To-Do
+====================
+
+Issues (if any) associated with license detections are listed with relevant details.
+License detections with issues are marked with a warning icon in the navigation pane.
+
+.. image:: data/license-explorer/license-explorer-todos.png
+
+Matches Table
+====================
 
 User can view the match details resulting the selected license :
 
-- ``Score``
+- ``License expression`` & ``SPDX License expression``
 - ``Matched length``
 - ``Match Coverage``
+- ``Score``
+- ``Rule relevance``
 - ``Matcher``
 - ``Matched Text``
     | User can click on the text to view a diff of Matched & Rule text
-    | (Requires ``--license-references`` flag)
 - ``Rule`` - User can click on the Rule to open the rule used byScanCode Toolkit in browser
-- ``SPDX License expression``
 
-File Regions Table:
 
-User can view the files in which selected license was detected:
+To view more information about match rule, you can click on info button beside Rule name.
+You can click on the Matched text to see the complete text as well as its difference with Rule text.
+
+.. Note::
+   Matched text is available in the scan only when ``--license-references`` flag is enabled in scan.
+
+.. figure:: data/license-explorer/license-explorer-matches.gif
+
+
+File Regions Table
+====================
+
+File regions table shows the files in which selected license was detected with following details
 
 - ``Path`` - Path of file, User can click on it to view the specific file in TableView
 - ``Lines`` - Specific lines in the file at which license was detected
-- ``Detection origin`` - Type of file
+- ``Detection origin`` - Type of origin (File or Package manifest)
+
+You can click on the data file path to view that path in Tableview.
+Similarly, detection origin is a clickable icon. It determines the source of detection.
+
+- Package icon indicates that the detection belongs to a package manifest,
+  you can click on it to view the source package manifest in :ref:`package-explorer`.
+
+- File icon indicates that the detection belongs to a plain file,
+  you can click on it to view the file in :ref:`table-view`.
 
-View License details, go to & from file <-> license explorer
---------------------------------------------------------------------------------
-.. image:: data/license-explorer/license-explorer-nav.gif
+.. figure:: data/license-explorer/license-explorer-fileregion.gif
 
-View Matched Text diff
---------------------------------------------
 
-.. image:: data/license-explorer/license-explorer-matchedtext.gif
 
 .. include:: ../rst_snippets/scans-used.rst
diff --git a/docs/source/ui-reference/package-explorer.rst b/docs/source/ui-reference/package-explorer.rst
@@ -30,7 +30,7 @@ User can select different filters:
 
 The navigation pane's width can also be adjusted as per convenience.
 
-.. image:: data/package-explorer/package-explorer-nav.gif
+.. figure:: data/package-explorer/package-explorer-nav.gif
 
 
 Package Details
@@ -78,7 +78,7 @@ User can see all the dependencies of the selected package in the table, with fol
 - ``Data file``
 - ``Extracted requirement``
 
-.. image:: data/package-explorer/package-details.gif
+.. figure:: data/package-explorer/package-details.gif
 
 Dependency Details
 --------------------

diff --git a/docs/source/ui-reference/pie-charts.rst b/docs/source/ui-reference/pie-charts.rst
@@ -36,8 +36,10 @@ You can hover over the legend items to highlight the corresponding pie chart seg
 
 You can click on the legend items to toggle the visibility of corresponding pie chart segments.
 
-.. image:: data/pie-charts/pie-charts-legend-toggle.gif
+.. figure:: data/pie-charts/pie-charts-legend-toggle.gif
+   :align: center
    :width: 100%
-   :alt: Click legend item to toggle segment visibility in Pie chart
+
+   Click legend item to toggle segment visibility in Pie chart
 
 .. include:: ../rst_snippets/scans-used.rst