Fixed sphinx errors, changed requirements versions, formatting and bu…

…ild errors Signed-off-by: Omkar Phansopkar <omkarphansopkar@gmail.com>
aboutcode-org · Sep 26, 2023 · 9e96f9e · 9e96f9e
1 parent 89083c7
commit 9e96f9e
Show file tree

Hide file tree

Showing 20 changed files with 148 additions and 204 deletions.
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1,5 +1,5 @@
 # Virtual environment
-.venv/
+venv/
 
 # sphinx build folder
 build/

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

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,7 +1,7 @@
-Sphinx>=7.0.0
+Sphinx>=5.0.2
+sphinx-rtd-theme>=1.0.0
+sphinx-reredirects >= 0.1.2
+doc8>=0.11.2
 sphinx-autobuild
-sphinx-rtd-theme
-sphinx-reredirects
-doc8
 jinja2
-markupSafe
+markupSafe
diff --git a/docs/source/contribute/building.rst b/docs/source/contribute/building.rst
@@ -30,7 +30,7 @@ Linux
 -----
 
 - Python 3.7 or later
-- `Node.js <https://nodejs.org/en/download/package-manager/>`_ 12.x or later
+- `Node.js <https://nodejs.org/en/download/package-manager/>`__ 12.x or later
 - npm 6.14.x or later
 - For CentOS (or linux distros without the new libstdc++) -
 
@@ -46,7 +46,7 @@ MacOS
 -----
 
 - Python 3.7 or later
-- `Node.js <https://nodejs.org/en/>`_ 12.x or later
+- `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)
@@ -55,7 +55,7 @@ Windows
 -------
 
 - Python v3.7 or later
-- `Node.js <https://nodejs.org/en/>`_ 12.x or later
+- `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
@@ -76,3 +76,30 @@ After building is done, you can find ScanCode-Workbench under
 are also built.
 
 .. Note:: A build for any of the three target platforms must be executed on the targeted platform.
+
+Building Documentation
+======================
+
+Create python environment, make docs
+
+
+.. code-block:: none
+
+   # Clone this repository
+   $ git clone https://github.com/nexB/scancode-workbench.git
+
+   # Go into the docs directory
+   $ cd docs/
+
+   # Setup virtual environment for python dependencies
+   $ python3 -m venv venv
+   $ source venv/bin/activate
+
+   # Install dependencies
+   $ pip install -r requirements.txt
+
+   # Build Documentation
+   $ make html
+
+   # Run Documentation server in dev mode
+   $ make dev
diff --git a/docs/source/how-to-guides/explore-your-data/navigate-chart-summary-view.rst b/docs/source/how-to-guides/explore-your-data/navigate-chart-summary-view.rst
@@ -3,7 +3,7 @@
 ================================================
 
 Display the Chart Summary view
-================
+====================================
 
 Once you have a SQLite file loaded into ScanCode Workbench, displaying the Chart
 Summary View is easy:

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
@@ -1,9 +1,9 @@
-================================================
+====================================================
 :index:`How-To: Navigate the License Explorer View`
-================================================
+====================================================
 
 Display the License Explorer view
-================
+===================================
 
 Once you have a SQLite file loaded into ScanCode Workbench,
 
@@ -24,7 +24,7 @@ You can search for any license detecttion / clue by typing in the search box on
 .. figure:: data/license-explorer-search.gif
 
 Matches & File regions table
-====================
+===================================
 
 For the selected license, you can view the 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

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
@@ -1,16 +1,16 @@
-================================================
+====================================================
 :index:`How-To: Navigate the Package Explorer View`
-================================================
+====================================================
 
 Display the Package Explorer view
-================
+===================================
 
 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`
 
 Select a Package or Dependency
-=========================
+====================================
 
 On the left pane, Packages are shown in a hierarchical manner as `Package Type` > `Package` > `Dependencies`
 Upon selecting a Package / Dependency, details of the entire entity is shown on the right.
@@ -30,7 +30,7 @@ You can filter the packages / dependencies by their data sources and/or dependen
 .. figure:: data/package-explorer-filter.gif
 
 Dependencies table
-====================
+========================
 
 When a package is selected, the dependencies for that package are shown in a table in the details pane showing Dependency information like `PURL, Scope, Data source ID, etc`
 

diff --git a/docs/source/how-to-guides/explore-your-data/navigate-tableview.rst b/docs/source/how-to-guides/explore-your-data/navigate-tableview.rst
@@ -3,7 +3,7 @@
 ================================================
 
 Display the Table view
-================
+============================
 
 Once you have a SQLite file loaded into ScanCode Workbench, you're automatically redirected to the Tableview.
 To navigate to Tableview from other views you can click on `Table View` in the sidebar or open the :kbd:`View` menu and select :kbd:`Table View`
@@ -12,15 +12,15 @@ To navigate to Tableview from other views you can click on `Table View` in the s
 
 
 Select a path
-===================
+========================
 
 You can collapse/expand the FileTree on the left and select a file/directory. Only the files under this path will be visible in the tableview
 
 .. figure:: data/tableview-path.gif
 
 
 Select Preset columns
-====================
+==========================
 
 You can select one of the available column groups, grouped based on their nature such as ``Copyright Cols``, ``Origin Cols``, ``License Cols``
 

diff --git a/docs/source/how-to-guides/load-your-data/import-json.rst b/docs/source/how-to-guides/load-your-data/import-json.rst
@@ -1,6 +1,6 @@
-==============================================
+=============================
 :index:`Import a JSON File`
-==============================================
+=============================
 
 To import a ScanCode JSON file:
 

diff --git a/docs/source/how-to-guides/lookup-scan-info/index.rst b/docs/source/how-to-guides/lookup-scan-info/index.rst
@@ -1,6 +1,6 @@
-==================================
+========================================
 :index:`Look Up Your Scan information`
-==================================
+========================================
 
 To view scan information:
 

diff --git a/docs/license.rst → docs/source/license.rst b/docs/license.rst → docs/source/license.rst
diff --git a/docs/source/technical-reference/index.rst b/docs/source/technical-reference/index.rst
@@ -13,98 +13,6 @@ Underlying Technology
 Platform Support
 ================
 
-ScanCode Workbench Supported Platforms
---------------------------------------
-
-Our approach for platform support is to focus on one primary release for each of Linux, MacOS and
-Windows. The Priority definitions are:
-
-* Primary - These are the primary platforms for build/test/release on an ongoing basis.
-* Secondary - These are platforms where the primary ScanCode Workbench release for the
-   corresponding OS Group should be forward-compatible, e.g., Windows 7 build should work on
-   Windows 10. Issues reported and traced to a Secondary platform may not be fixed.
-* Tertiary - These are any other platforms not listed as Primary or Secondary. In these cases, we
-   will help users help themselves, but we are likely not to fix Issues that only surface on a
-   Tertiary platform.
-
-+-------------+------------------+----------+------------+-----------------------------------------+
-| OS Group    |  Desktop OS      |    Arch  |  Priority  |      Notes                              |
-|             |  Version         |          |            |                                         |
-+=============+==================+==========+============+=========================================+
-|  Windows    |   Windows 7      |    x64   |      2     |                                         |
-+-------------+------------------+----------+------------+-----------------------------------------+
-|  Windows    |  Windows 10      |    x64   |     1      | Verified to be able to run the prebuilt |
-+-------------+------------------+----------+------------+-----------------------------------------+
-|  Windows    | Windows 11       |    x64   |     1      | Verified to be able to run the prebuilt |
-+-------------+------------------+----------+------------+-----------------------------------------+
-|  MacOS      | 10.15 Catalina   |    x64   |      2     |                                         |
-+-------------+------------------+----------+------------+-----------------------------------------+
-|  MacOS      | 11 Big Sur       |x64, arm64|    2       | Verified to be able to run the prebuilt |
-+-------------+------------------+----------+------------+-----------------------------------------+
-|  MacOS      | 12 Monterey      |x64, arm64|     1      | Verified to be able to run the prebuilt |
-+-------------+------------------+----------+------------+-----------------------------------------+
-|  MacOS      | 13 Ventura       |x64, arm64|     1      | Verified to be able to run the prebuilt |
-+-------------+------------------+----------+------------+-----------------------------------------+
-| Linux Deb   | Ubuntu 12.04     |    x64   |     2      | From Electron Docs: The prebuilt ia32   |
-|             |                  |          |            | (i686) and x64 (amd64) binaries of      |
-|             |                  |          |            | Electron are built on Ubuntu 12.04.     |
-+-------------+------------------+----------+------------+-----------------------------------------+
-| Linux Deb   | Ubuntu 14.xx     |    x64   |     2      | Verified to be able to run the prebuilt |
-|             |                  |          |            | binaries of Electron.                   |
-+-------------+------------------+----------+------------+-----------------------------------------+
-| Linux Deb   | Ubuntu 16.xx     |    x64   |     1      | Verified to be able to run the prebuilt |
-|             |                  |          |            | binaries of Electron.                   |
-+-------------+------------------+----------+------------+-----------------------------------------+
-| Linux Deb   | Ubuntu 18.xx     |    x64   |     1      | Verified to be able to run the prebuilt |
-|             |                  |          |            | binaries of Electron.                   |
-+-------------+------------------+----------+------------+-----------------------------------------+
-| Linux Deb   | Ubuntu 20.xx     |    x64   |     1      | Verified to be able to run the prebuilt |
-|             |                  |          |            | binaries of Electron.                   |
-+-------------+------------------+----------+------------+-----------------------------------------+
-| Linux Deb   | Ubuntu 22.xx     |    x64   |     1      | Verified to be able to run the prebuilt |
-|             |                  |          |            | binaries of Electron.                   |
-+-------------+------------------+----------+------------+-----------------------------------------+
-|   Linux     |  Fedora 21       |    x64   |     2      | Verified to be able to run the prebuilt |
-|             |                  |          |            | binaries of Electron.                   |
-+-------------+------------------+----------+------------+-----------------------------------------+
-|   Linux     |  Debian 8        |    x64   |     2      | Verified to be able to run the prebuilt |
-|             |                  |          |            | binaries of Electron.                   |
-+-------------+------------------+----------+------------+-----------------------------------------+
-| Linux RH    |  CentOS 7.xx     |    x64   |     ?      |                                         |
-+-------------+------------------+----------+------------+-----------------------------------------+
-| Linux RH    |  RHEL 7.xx       |    x64   |     ?      |                                         |
-+-------------+------------------+----------+------------+-----------------------------------------+
-
-Electron Supported Platforms
-----------------------------
-
-https://electronjs.org/docs/tutorial/support#supported-platforms
-
-The following platforms are supported by Electron:
-
-MacOS
-^^^^^
-
-Binaries for both x64 & arm64 are provided for MacOS, and the minimum MacOS version supported is MacOS 10.9
-
-Windows
-^^^^^^^
-
-Windows 7 and later are supported, while older operating systems are not supported (and do not
-work). Both ia32 (x86) and x64 (amd64) binaries are provided for Windows. Please note: the ARM
-version of Windows is not supported for now.
-
-Linux
-^^^^^
-
-The prebuilt ia32 (i686) and x64 (amd64) binaries of Electron are built on Ubuntu 12.04, and the
-ARM binary is built against ARM v7 with hard-float ABI and NEON for Debian Wheezy.
-
-Whether the prebuilt binary can run on a distribution depends on whether the distribution includes
-the libraries that Electron is linked to on the building platform, so only Ubuntu 12.04 is
-guaranteed to work, but the following platforms are also verified to be able to run the prebuilt
-binaries of Electron:
-
-- Ubuntu 12.04 and later
-- Fedora 21
-- Debian 8
+* Linux - ``x64``
+* Windows 10/11 - ``x64``
+* MacOS - ``x64``, ``arm64``
diff --git a/docs/source/ui-reference/chart-summary-view.rst b/docs/source/ui-reference/chart-summary-view.rst
@@ -1,4 +1,4 @@
-.. _license-explorer:
+.. _chart-summary-view:
 
 ===========================
 :index:`Chart Summary View`

diff --git a/docs/source/ui-reference/copyright-info-dashboard.rst b/docs/source/ui-reference/copyright-info-dashboard.rst
@@ -1,6 +1,6 @@
-============================
+===================================
 :index:`Copyright Info Dashboard`
-============================
+===================================
 
 Scan must have ``--license`` option for License Info Dashboard
 

diff --git a/docs/source/ui-reference/dependency-info-dashboard.rst b/docs/source/ui-reference/dependency-info-dashboard.rst
@@ -1,6 +1,6 @@
-============================
+=====================================
 :index:`Dependency Info Dashboard`
-============================
+=====================================
 
 Scan must have ``--package`` option for Dependency Info Dashboard
 

diff --git a/docs/source/ui-reference/license-explorer.rst b/docs/source/ui-reference/license-explorer.rst
@@ -7,7 +7,7 @@
 Details of Top level License detections and clues
 
 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
@@ -18,35 +18,36 @@ These sections' height & navigation pane's width can be adjusted as per convenie
 
 
 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
 
 Matches Table
-User can view the match details resulting the selected license 
-    - ``Score``
-    - ``Matched length``
-    - ``Match Coverage``
-    - ``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 by scancode-toolkit in browser
-    - ``SPDX License expression``
+User can view the match details resulting the selected license
+
+- ``Score``
+- ``Matched length``
+- ``Match Coverage``
+- ``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 by scancode-toolkit in browser
+- ``SPDX License expression``
 
 File Regions Table
 User can view the files in which selected license was detected
-    - ``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
+- ``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
 
 View License details, go to & from file <-> license explorer
---------------------
+--------------------------------------------------------------------------------
 .. image:: data/license-explorer/license-explorer-nav.gif
 
 View Matched Text diff
-------------------------
+--------------------------------------------
 
 .. image:: data/license-explorer/license-explorer-matchedtext.gif
diff --git a/docs/source/ui-reference/license-info-dashboard.rst b/docs/source/ui-reference/license-info-dashboard.rst
@@ -1,6 +1,6 @@
-============================
+================================
 :index:`License Info Dashboard`
-============================
+================================
 
 Scan must have ``--license`` option for License Info Dashboard