Updated docs config, dark theme, UI reference updates

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

docs/.readthedocs.yml

@@ -0,0 +1,29 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build in latest ubuntu/python
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build PDF & ePub
+formats:
+  - epub
+  - pdf
+
+# Where the Sphinx conf.py file is located
+sphinx:
+   configuration: docs/source/conf.py
+
+# Setting the python version and doc build requirements
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

docs/requirements.txt

@@ -1,7 +1,9 @@
 Sphinx>=5.0.2
+sphinx-autobuild
+sphinx-reredirects>=0.1.2
 sphinx-rtd-theme>=1.0.0
-sphinx-reredirects >= 0.1.2
+sphinx-rtd-dark-mode>=1.3.0
 doc8>=0.11.2
-sphinx-autobuild
 jinja2
 markupSafe
+sphinx-copybutton

docs/source/conf.py

@@ -20,6 +20,9 @@
 project = 'ScanCode Workbench Documentation'
 copyright = 'nexB Inc. and others'
 author = 'nexB Inc. and others'
+github_user = "nexB"
+github_repo = "scancode-workbench"
+github_branch = "update/docs"
 
 
 # -- General configuration ---------------------------------------------------
@@ -30,7 +33,10 @@
 extensions = [
     "sphinx.ext.intersphinx",
     'sphinx_rtd_theme',
-    "sphinx_reredirects"
+    "sphinx_rtd_dark_mode",
+    "sphinx_reredirects",
+    "sphinx.ext.extlinks",
+    "sphinx_copybutton",
 ]
 
 
@@ -73,9 +79,9 @@
 
 html_context = {
     "display_github": True,
-    "github_user": "nexB",
-    "github_repo": "scancode-workbench",
-    "github_version": "develop",  # branch
+    "github_user": github_user,
+    "github_repo": github_repo,
+    "github_version": github_branch,  # branch
     "conf_py_path": "/docs/source/",  # path in the checkout to the docs root
 }
 
@@ -103,8 +109,14 @@
 
 """
 
+# Define reusable URLs using extlinks
+extlinks = {
+    'github_repo': (f"https://github.com/{github_user}/{github_repo}/%s", '%s'),
+    'scan_samples': (f"https://github.com/{github_user}/{github_repo}/tree/{github_branch}/samples/%s", '%s'),
+}
+
 # -- Options for LaTeX output -------------------------------------------------
 
 latex_elements = {
     'classoptions': ',openany,oneside'
-}
+}

docs/source/contribute/building.rst

@@ -9,19 +9,19 @@ Clone, Install, Build and Run
 
 You'll need `Node.js <https://nodejs.org/>`__ (which comes with `npm <http://npmjs.com/>`__) installed on your computer in order to build this app. (See below for a list of platform-specific requirements.) Then, from your command line:
 
-.. code-block:: none
+.. code-block:: bash
 
    # Clone this repository
-   $ git clone https://github.com/nexB/scancode-workbench.git
+   git clone https://github.com/nexB/scancode-workbench.git
 
    # Go into the repository
-   $ cd scancode-workbench
+   cd scancode-workbench
 
    # Install dependencies and run the app (Native dependencies are handled automatically)
-   $ npm install
+   npm install
 
    # Run the app
-   $ npm start
+   npm start
 
 Building Requirements
 =====================
@@ -34,13 +34,23 @@ Linux
 - npm 6.14.x or later
 - For CentOS (or linux distros without the new libstdc++) -
 
-   -  Install the new libstdc++ library: ``yum provides libstdc++``.
+   -  Install the new libstdc++ library: 
+
+      .. code-block:: bash
+      
+         yum provides libstdc++
+         
    -  Update LD_LIBRARY_PATH:
 
-      ``export LD_LIBRARY_PATH="/usr/local/lib64/:$LD_LIBRARY_PATH"``
+      .. code-block:: bash
+      
+         export LD_LIBRARY_PATH="/usr/local/lib64/:$LD_LIBRARY_PATH"
+
    -  Run the application with ``no-sandbox`` option:
 
-      ``./ScanCode\ Workbench-linux-x64/ScanCode\ Workbench --no-sandbox``
+      .. code-block:: bash
+      
+         ./ScanCode\ Workbench-linux-x64/ScanCode\ Workbench --no-sandbox
 
 MacOS
 -----
@@ -49,31 +59,43 @@ MacOS
 - `Node.js <https://nodejs.org/en/>`__ 12.x or later
 - npm 6.14.x or later
 - Command Line Tools for `Xcode <https://developer.apple.com/xcode/downloads/>`_
-  (run ``xcode-select --install`` to install)
+   Install using:
+
+   .. code-block:: bash
+   
+      xcode-select --install
 
 Windows
 -------
 
 - Python v3.7 or later
+
+  * Make sure your Python path is set. To verify, open a command prompt and see the python version:
+
+   .. code-block:: bash
+   
+      python --version
+
 - `Node.js <https://nodejs.org/en/>`__ 12.x or later
 - npm 6.14.x or later
 
-  * Make sure your Python path is set. To verify, open a command prompt and type
-    ``python --version``. Then, the version of python will be displayed.
 
 Release Instructions
 ====================
 
 You can build a ``dist`` directory and a ``tar/zip`` file containing executable for your platform
 by running:
 
-.. code-block:: none
+.. code-block:: bash
 
-   $ npm run publish
+   npm run publish
 
 After building is done, you can find ScanCode-Workbench under
-``dist/ScanCode-Workbench-<os>-<arch>-<version>``. Archives (``tar.gz`` and ``.zip``)
-are also built.
+``dist/ScanCode-Workbench-<os>-<arch>-<version>``.
+
+Archives are also built as:
+   - ``tar.gz`` - Linux / MacOS
+   - ``.zip`` - Windows
 
 .. Note:: A build for any of the three target platforms must be executed on the targeted platform.
 
@@ -86,20 +108,20 @@ Create python environment, make docs
 .. code-block:: none
 
    # Clone this repository
-   $ git clone https://github.com/nexB/scancode-workbench.git
+   git clone https://github.com/nexB/scancode-workbench.git
 
    # Go into the docs directory
-   $ cd docs/
+   cd docs/
 
    # Setup virtual environment for python dependencies
-   $ python3 -m venv venv
-   $ source venv/bin/activate
+   python3 -m venv venv
+   source venv/bin/activate
 
    # Install dependencies
-   $ pip install -r requirements.txt
+   pip install -r requirements.txt
 
    # Build Documentation
-   $ make html
+   make html
 
    # Run Documentation server
-   $ make docs
+   make docs

docs/source/getting-started/index.rst

@@ -16,13 +16,23 @@ Download and Install
 
 -  Note - For CentOS (or linux distros without the new libstdc++):
 
-   -  Install the new libstdc++ library: ``yum provides libstdc++``.
+   -  Install the new libstdc++ library:
+
+      .. code-block:: bash
+         
+         yum provides libstdc++
+
    -  Update LD_LIBRARY_PATH:
 
-      ``export LD_LIBRARY_PATH="/usr/local/lib64/:$LD_LIBRARY_PATH"``
+      .. code-block:: bash
+
+         export LD_LIBRARY_PATH="/usr/local/lib64/:$LD_LIBRARY_PATH"
+
    -  Run the application with ``no-sandbox`` option:
 
-      ``./ScanCode\ Workbench-linux-x64/ScanCode\ Workbench --no-sandbox``
+      .. code-block:: bash
+
+         ./ScanCode\ Workbench-linux-x64/ScanCode\ Workbench --no-sandbox
 
 -  If you're interested in digging into the code, you can also use ScanCode Workbench by cloning
    the GitHub repository and building it yourself -- see the :ref:`Contribute/Building<building>`

docs/source/rst_snippets/copyright-pie-charts-notice.rst

@@ -0,0 +1,2 @@
+.. note::
+   Legend items are not available on the :ref:`copyright-info-dashboard` due to long copyright statements.

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

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

docs/source/rst_snippets/scans-used.rst

@@ -0,0 +1,9 @@
+.. note::
+  Refer the titlebar to see the name of the sample scan used in the screenshot.
+  Sample scans:
+
+  - :scan_samples:`anglesharp.css.0.16.4-scan-results-without-text-referendces.json`
+  - :scan_samples:`aws-java-sdk-core-1.12.262-sources.jar-v32rc4results-todo.json`
+  - :scan_samples:`hazelcast-3293_v32.0.0rc3.json`
+  - :scan_samples:`scancode-32.0.0rc4_python_sample-wref.json`
+  - :scan_samples:`zjsonpatch-0.3.0.jar-v32rc4results.json`

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

@@ -15,3 +15,8 @@ values for the selected directory tree node and attribute and the number of time
 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

@@ -1,3 +1,5 @@
+.. _copyright-info-dashboard:
+
 ===================================
 :index:`Copyright Info Dashboard`
 ===================================
@@ -16,6 +18,10 @@ Summary of Licenses:
     - Copyright Notices
     - Copyright Authors
 
-Note - Legends are not shown for copyright charts due to large length of copyright statements
+.. include::  /rst_snippets/refer-pie-charts.rst
+
+.. include::  /rst_snippets/copyright-pie-charts-notice.rst
+
+.. image:: data/copyright-info/copyright-info.png
 
-.. image:: data/copyright-info/copyright-info.gif
+.. include:: ../rst_snippets/scans-used.rst

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

@@ -1,3 +1,5 @@
+.. _dependency-info-dashboard:
+
 =====================================
 :index:`Dependency Info Dashboard`
 =====================================
@@ -19,6 +21,20 @@ Summary of Dependencys:
     - Resolved dependencies
     - Optional dependencies
 
-Tip - Slices of pie-chart can be hidden/shown by clicking on the corresponding legend below charts
+.. include::  /rst_snippets/refer-pie-charts.rst
+
+************************************************************
+Package type wise Scope  summary
+************************************************************
+.. image:: data/dependency-info/dependency-info-scope-table.png
+
+
+************************************************************
+Charts
+************************************************************
+
+.. image:: data/dependency-info/dependency-info-charts_1.png
+
+.. image:: data/dependency-info/dependency-info-charts_2.png
 
-.. image:: data/dependency-info/dependency-info.gif
+.. include:: ../rst_snippets/scans-used.rst

docs/source/ui-reference/directory-tree.rst

@@ -17,4 +17,6 @@ Demo of filetree on different views:
 
 .. image:: data/directory-tree/directory-tree-copyright.gif
 
-.. image:: data/directory-tree/directory-tree-chartview.gif
+.. image:: data/directory-tree/directory-tree-chartview.gif
+
+.. include:: ../rst_snippets/scans-used.rst

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

@@ -17,6 +17,8 @@ Summary of files:
     - File Types
     - Mime Types
 
-Tip - Slices of pie-chart can be hidden/shown by clicking on the corresponding legend below charts
+.. include::  /rst_snippets/refer-pie-charts.rst
 
-.. image:: data/file-info/file-info.gif
+.. image:: data/file-info/file-info.png
+
+.. include:: ../rst_snippets/scans-used.rst

docs/source/ui-reference/index.rst

@@ -9,6 +9,7 @@
 
    directory-tree
    table-view
+   pie-charts
    file-info-dashboard
    license-info-dashboard
    copyright-info-dashboard

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

@@ -4,7 +4,13 @@
 :index:`License Explorer`
 ============================
 
-Details of Top level License detections and clues
+Details of all the License detections and clues including Matches as well as files in which they 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 in scancode-toolkit
+.. :doc:`scancode-toolkit:reference/license-detection-reference#what-is-a-licensedetection`
 
 License Navigation Pane
 -------------------------------
@@ -22,7 +28,7 @@ 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 - Shown only for clues, indicating clue's confidence about the license
+Score - Clue's confidence about the license (Shown only for clues)
 
 Matches Table
 User can view the match details resulting the selected license
@@ -50,4 +56,6 @@ View License details, go to & from file <-> license explorer
 View Matched Text diff
 --------------------------------------------
 
-.. image:: data/license-explorer/license-explorer-matchedtext.gif
+.. image:: data/license-explorer/license-explorer-matchedtext.gif
+
+.. include:: ../rst_snippets/scans-used.rst