Added Docs CI, fixed minor docs errors

Signed-off-by: Omkar Phansopkar <[email protected]>
aboutcode-org · Oct 17, 2023 · 7e00d58 · 7e00d58
1 parent be37218
commit 7e00d58
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 -r docs/requirements.txt
+
+ - 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