Added Docs CI, fixed minor docs errors

Signed-off-by: Omkar Phansopkar <[email protected]>
aboutcode-org · Oct 17, 2023 · 85e3496 · 85e3496
1 parent be37218
commit 85e3496
Show file tree

Hide file tree

Showing 26 changed files with 174 additions and 84 deletions.
diff --git a/.github/workflows/docs-ci.yml b/.github/workflows/docs-ci.yml
@@ -0,0 +1,36 @@
+name: CI Documentation
+
+on: [push, pull_request]
+
+permissions:
+  contents: read # to fetch code (actions/checkout)
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+
+    strategy:
+      max-parallel: 4
+      matrix:
+        python-version: [3.9]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Dependencies
+        run:  pip install -e .[docs]
+
+      - name: Check Sphinx Documentation build minimally
+        working-directory: ./docs
+        run: sphinx-build -E -W source build
+
+      - name: Check for documentation style errors
+        working-directory: ./docs
+        run: ./scripts/doc8_style_check.sh
+
diff --git a/CODE_OF_CONDUCT.rst b/CODE_OF_CONDUCT.rst
@@ -65,7 +65,7 @@ Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may
 be reported by contacting the project team at [email protected]
-or on the Gitter chat channel at https://gitter.im/aboutcode-org/discuss .
+or on the Gitter chat channel at https://matrix.to/#/#aboutcode-org_discuss:gitter.im
 All complaints will be reviewed and investigated and will result in a
 response that is deemed necessary and appropriate to the circumstances.
 The project team is obligated to maintain confidentiality with regard to

diff --git a/README.md b/README.md
@@ -11,7 +11,7 @@ license and other notices identified by
 and other interesting information in your code.
 
 ScanCode Workbench is based on
-[Electron](https://electron.atom.io/) and will be the primary desktop/GUI tool 
+[Electron](https://www.electronjs.org/) and will be the primary desktop/GUI tool 
 for using nexB’s [AboutCode tools](https://github.com/nexB/aboutcode). This app 
 works on Windows, OS X and Linux operating systems.
 
@@ -96,6 +96,6 @@ See the NOTICE file for more details.
 
 If you have a question, a suggestion or find a bug, enter an issue.
 
-[![Gitter chat](https://badges.gitter.im/aboutcode-org/gitter.png)](https://gitter.im/aboutcode-org/discuss)
+[![Gitter chat](https://badges.gitter.im/aboutcode-org/gitter.png)](https://matrix.to/#/#aboutcode-org_discuss:gitter.im)
 
-For questions and chats, you can join the Gitter channel at https://gitter.im/aboutcode-org/discuss
+For questions and chats, you can join the Gitter channel at https://matrix.to/#/#aboutcode-org_discuss:gitter.im
diff --git a/docs/scripts/doc8_style_check.sh b/docs/scripts/doc8_style_check.sh
diff --git a/docs/scripts/sphinx_build_link_check.sh b/docs/scripts/sphinx_build_link_check.sh
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -112,7 +112,7 @@
 # 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'),
+    'scan_samples': (f"https://github.com/{github_user}/{github_repo}/blob/{github_branch}/samples/%s", '%s'),
 }
 
 # -- Options for LaTeX output -------------------------------------------------

diff --git a/docs/source/contribute/building.rst b/docs/source/contribute/building.rst
@@ -7,7 +7,7 @@
 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:
+You'll need `Node.js <https://nodejs.org/en>`__ (which comes with `npm <https://www.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:: bash
 
@@ -33,23 +33,23 @@ Linux
 - `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++) -
-   
-   -  Install the new libstdc++ library: 
+
+   -  Install the new libstdc++ library:
 
       .. code-block:: bash
-      
+
          yum provides libstdc++
-         
+
    -  Update LD_LIBRARY_PATH:
-      
+
       .. code-block:: bash
-      
+
          export LD_LIBRARY_PATH="/usr/local/lib64/:$LD_LIBRARY_PATH"
 
    -  Run the application with ``no-sandbox`` option:
-   
+
       .. code-block:: bash
-      
+
          ./ScanCode\ Workbench-linux-x64/ScanCode\ Workbench --no-sandbox
 
 MacOS
@@ -58,11 +58,11 @@ MacOS
 - Python 3.7 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/>`_
+- Command Line Tools for `Xcode <https://developer.apple.com/xcode/resources/>`_
    Install using:
 
    .. code-block:: bash
-   
+
       xcode-select --install
 
 Windows
@@ -73,7 +73,7 @@ Windows
   * 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

diff --git a/docs/source/contribute/community-channels.rst b/docs/source/contribute/community-channels.rst
@@ -4,4 +4,4 @@
 
 If you have a question, a suggestion or find a bug, `enter an issue <https://github.com/nexB/scancode-workbench/issues>`__.
 
-For questions and chats, you can join the Gitter channel at https://gitter.im/aboutcode-org/discuss
+For questions and chats, you can join the Gitter channel at `<https://matrix.to/#/#aboutcode-org_discuss:gitter.im>`_
diff --git a/docs/source/getting-started/index.rst b/docs/source/getting-started/index.rst
@@ -9,26 +9,30 @@ Download and Install
 
 - 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`.
+
+-
+   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++), follow these steps:
 
    -  Install the new libstdc++ library:
-   
+
       .. code-block:: bash
-         
+
          yum provides libstdc++
 
    -  Update LD_LIBRARY_PATH:
-      
+
       .. code-block:: bash
 
          export LD_LIBRARY_PATH="/usr/local/lib64/:$LD_LIBRARY_PATH"
 
    -  Run the application with ``no-sandbox`` option:
-   
+
       .. code-block:: bash
 
          ./ScanCode\ Workbench-linux-x64/ScanCode\ Workbench --no-sandbox

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
@@ -9,7 +9,10 @@ Once you have a SQLite file loaded into ScanCode Workbench, displaying the Chart
 Summary View is easy:
 
 * Select a file or directory in the Tree View on the left.
-* Click on `Chart Summary View` in the sidebar or open the :kbd:`View` menu and select :kbd:`Chart Summary View` (keyboard shortcut: :kbd:`Ctrl+Shift+D` or :kbd:`⌘+Shift+D`).
+*
+  Click on `Chart Summary View` in the sidebar or open the
+  :kbd:`View` menu and select :kbd:`Chart Summary View`
+  (keyboard shortcut: :kbd:`Ctrl+Shift+D` or :kbd:`⌘+Shift+D`).
 
 Select an attribute
 ===================
@@ -36,4 +39,4 @@ directory or file.
 
 .. figure:: data/chart-summary-filetree.gif
 
-For entire UI reference, Read :ref:`chart-summary-view` 
+For entire UI reference, Read :ref:`chart-summary-view`
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
@@ -7,12 +7,16 @@ Display the License Explorer view
 
 Once you have a SQLite file loaded into ScanCode Workbench,
 
-* Click on `License Explorer` in the sidebar or open the :kbd:`View` menu and select :kbd:`License Explorer`
+Click on `License Explorer` in the sidebar or open the :kbd:`View` menu
+and select :kbd:`License Explorer`
+
 
 Select 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
+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
 
@@ -26,9 +30,10 @@ You can search for any license detecttion / clue by typing in the search box on
 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.
+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
 
 .. figure:: data/license-explorer-table.gif
 
-For entire UI reference, Read :ref:`license-explorer` 
+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
@@ -2,24 +2,27 @@
 :index:`How-To: Navigate the Package Explorer View`
 ====================================================
 
-.. include:: ../definitions.rst
+.. include:: ../../definitions.rst
 
 Display the Package Explorer view
 ===================================
 
-Packages are uniquely identified using PURLs. ||purl_description|
+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`
+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`
+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.
 
-For a Package, information like `PURL, namespace, Declared license expression, Dependencies table, etc` are shown.
+For a Package, information like
+`PURL, namespace, Declared license expression, Dependencies table, etc` are shown.
 
 For a Dependency, information like `Scope, Data file, Data source ID, etc` are shown.
 
@@ -29,14 +32,17 @@ For a Dependency, information like `Scope, Data file, Data source ID, etc` are s
 Filters
 ====================
 
-You can filter the packages / dependencies by their data sources and/or dependency flags by selecting filter values in the top-left
+You can filter the packages / dependencies by their data sources and/or
+dependency flags by selecting filter values in the top-left
 
 .. 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`
+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`
 
 You can sort the table as per convenience.
 
@@ -45,4 +51,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, See :ref:`package-explorer` 
+For entire UI reference, See :ref:`package-explorer`
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
@@ -5,26 +5,30 @@
 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`
-
-* Click on `Package Explorer` in the sidebar or open the :kbd:`View` menu and select :kbd:`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`
 
+Click on `Package Explorer` in the sidebar or open the :kbd:`View`
+menu and select :kbd:`Table View`
 
 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
+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``
+You can select one of the available column groups, grouped based on their
+nature such as ``Copyright Cols``, ``Origin Cols``, ``License Cols``
 
 .. figure:: data/tableview-column-groups.gif
 
 
-For entire UI reference, Read :ref:`table-view` 
+For entire UI reference, Read :ref:`table-view`
diff --git a/docs/source/how-to-guides/load-your-data/open-save-sqlite-file.rst b/docs/source/how-to-guides/load-your-data/open-save-sqlite-file.rst
@@ -5,7 +5,8 @@
 Open a SQLite File
 ==================
 
-Once you've imported your JSON scan it is parsed & saved as a SQLite file, which can be later imported quickly compared to opening json scan again
+Once you've imported your JSON scan it is parsed & saved as a SQLite file,
+which can be later imported quickly compared to opening json scan again
 
 * To open a SQLite File:
 

diff --git a/docs/source/rst_snippets/copyright-pie-charts-notice.rst b/docs/source/rst_snippets/copyright-pie-charts-notice.rst
@@ -1,2 +1,2 @@
 .. note::
-   Legend items are not available on the :ref:`copyright-info-dashboard` due to long copyright statements.
+   Legend items are not available on the :ref:`copyright-info-dashboard` due to long copyright statements.
diff --git a/docs/source/technical-reference/index.rst b/docs/source/technical-reference/index.rst
@@ -7,7 +7,7 @@
 Underlying Technology
 =====================
 
--  ScanCode Workbench is based on `Electron <https://electron.atom.io/>`__ and works on
+-  ScanCode Workbench is based on `Electron <https://www.electronjs.org/>`__ and works on
    Windows, OS X and Linux operating systems.
 
 Platform Support

diff --git a/docs/source/ui-reference/copyright-info-dashboard.rst b/docs/source/ui-reference/copyright-info-dashboard.rst
@@ -4,7 +4,8 @@
 :index:`Copyright Info Dashboard`
 ===================================
 
-Copyright info dashboard summarizes the copyright information detected in scan for files under the selected path.
+Copyright info dashboard summarizes the copyright information detected
+in scan for files under the selected path.
 Scan must have ``--copyright`` option for Copyright Info Dashboard.
 
 Summary of Copyrights:
@@ -18,11 +19,14 @@ Summary of Copyrights:
 
 - Pie charts
     - Copyright Holders
-        Distribution of unique copyright holders indicating the number of files in which each copyright holder was detected.
+        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.
+        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.
+        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/dependency-info-dashboard.rst b/docs/source/ui-reference/dependency-info-dashboard.rst
@@ -4,7 +4,8 @@
 :index:`Dependency Info Dashboard`
 =====================================
 
-Dependency info dashboard summarizes the dependencies information detected in scan for files under the selected path.
+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:

diff --git a/docs/source/ui-reference/directory-tree.rst b/docs/source/ui-reference/directory-tree.rst
@@ -19,4 +19,4 @@ Demo of filetree on different views:
 
 .. image:: data/directory-tree/directory-tree-chartview.gif
 
-.. include:: ../rst_snippets/scans-used.rst
+.. include:: ../rst_snippets/scans-used.rst