Merge pull request #602 from nexB/update/docs

Update Documentation

.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
+

.readthedocs.yml

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

CODE_OF_CONDUCT.rst

@@ -0,0 +1,86 @@
+Contributor Covenant Code of Conduct
+====================================
+
+Our Pledge
+----------
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our
+project and our community a harassment-free experience for everyone,
+regardless of age, body size, disability, ethnicity, gender identity and
+expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+Our Standards
+-------------
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+-  Using welcoming and inclusive language
+-  Being respectful of differing viewpoints and experiences
+-  Gracefully accepting constructive criticism
+-  Focusing on what is best for the community
+-  Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+-  The use of sexualized language or imagery and unwelcome sexual
+   attention or advances
+-  Trolling, insulting/derogatory comments, and personal or political
+   attacks
+-  Public or private harassment
+-  Publishing others’ private information, such as a physical or
+   electronic address, without explicit permission
+-  Other conduct which could reasonably be considered inappropriate in a
+   professional setting
+
+Our Responsibilities
+--------------------
+
+Project maintainers are responsible for clarifying the standards of
+acceptable behavior and are expected to take appropriate and fair
+corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit,
+or reject comments, commits, code, wiki edits, issues, and other
+contributions that are not aligned to this Code of Conduct, or to ban
+temporarily or permanently any contributor for other behaviors that they
+deem inappropriate, threatening, offensive, or harmful.
+
+Scope
+-----
+
+This Code of Conduct applies both within project spaces and in public
+spaces when an individual is representing the project or its community.
+Examples of representing a project or community include using an
+official project e-mail address, posting via an official social media
+account, or acting as an appointed representative at an online or
+offline event. Representation of a project may be further defined and
+clarified by project maintainers.
+
+Enforcement
+-----------
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may
+be reported by contacting the project team at pombredanne@gmail.com
+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
+the reporter of an incident. Further details of specific enforcement
+policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in
+good faith may face temporary or permanent repercussions as determined
+by other members of the project’s leadership.
+
+Attribution
+-----------
+
+This Code of Conduct is adapted from the `Contributor Covenant`_ ,
+version 1.4, available at
+https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+.. _Contributor Covenant: https://www.contributor-covenant.org

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.
 
@@ -23,8 +23,8 @@ works on Windows, OS X and Linux operating systems.
 * You can [download the latest release](https://github.com/nexB/scancode-workbench/releases) 
 for your operating system or build it yourself (see below). Once downloaded, you 
 can find `ScanCode-Workbench` under `dist/ScanCode-Workbench-<os>-<arch>-<version>`
-* ScanCode Workbench >= v2 is only compatible with scans from 
-[ScanCode v2.0.0](https://github.com/nexB/scancode-toolkit/releases) and 
+* ScanCode Workbench >= v4 is only compatible with scans from 
+[ScanCode v32.0.0](https://github.com/nexB/scancode-toolkit/releases) and 
 above which are run with the ScanCode `-i` option. For a list of available ScanCode 
 options see [How To: Set what will be detected in a scan](https://scancode-toolkit.readthedocs.io/en/latest/tutorials/how_to_set_what_will_be_detected_in_a_scan.html)
 
@@ -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

archive_builder.py

@@ -1,6 +1,6 @@
 #!/usr/bin/python
 
-# Copyright (c) 2017 - 2019 nexB Inc. http://www.nexb.com/ - All rights reserved.
+# Copyright (c) nexB Inc. and others. All rights reserved.
 
 """
 Run this script to build ScanCode Workbench. The script detects which OS

attribution.html

@@ -58,13 +58,13 @@ <h2>About ScanCode Workbench 4.0.0:</h2>
     </p>
 
     <pre>
-  Copyright (c) 2016 - 2019 nexB Inc. and others. All rights reserved.</pre
+      Copyright (c) nexB Inc. and others. All rights reserved.</pre
       >
       <pre>
   Software license
   ================
 
-  Copyright (c) 2016 nexB Inc. and others. All rights reserved.
+  Copyright (c) nexB Inc. and others. All rights reserved.
   https://nexb.com and https://github.com/nexB/scancode-workbench/
   The ScanCode Workbench software is licensed under the Apache License version 2.0.
   ScanCode is a trademark of nexB Inc.

docs/Makefile

@@ -5,6 +5,7 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
+SPHINXAUTOBUILD = sphinx-autobuild
 SOURCEDIR     = source
 BUILDDIR      = build
 
@@ -14,6 +15,13 @@ help:
 
 .PHONY: help Makefile
 
+# Run the development server using sphinx-autobuild
+docs:
+	@echo
+	@echo "Starting up the docs server..."
+	@echo
+	$(SPHINXAUTOBUILD) --port 8000 --watch ${SOURCEDIR} $(SOURCEDIR) "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

docs/README.md

@@ -2,13 +2,17 @@
 The first step you want to do is create the python virtual environment:
 ```
 $ cd docs/
-$ python3 -m venv .venv
-$ source .venv/bin/active
+$ python3 -m venv venv
+$ source venv/bin/activate
 $ pip install -r requirements.txt
 ```
 
-Now, you can run the various Spinx build things:
+Run Sphinx documentation server:
+```
+$ make docs
+```
+
+Build Sphinx documentation
 ```
 $ make html
-$ etc
 ```

docs/make.bat

@@ -1,35 +1,47 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=source
-set BUILDDIR=build
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+if "%SPHINXAUTOBUILD%" == "" (
+	set SPHINXAUTOBUILD=sphinx-autobuild
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+if "%1" == "docs" goto docs
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:docs
+@echo
+@echo Starting up the docs server...
+@echo
+%SPHINXAUTOBUILD% --port 8000 --watch %SOURCEDIR% %SOURCEDIR% %BUILDDIR%\html %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -1,26 +1,9 @@
-alabaster==0.7.12
-Babel==2.9.1
-certifi==2019.11.28
-chardet==3.0.4
-colorama==0.4.3
-docutils==0.16
-idna==2.9
-imagesize==1.2.0
-Jinja2==2.11.3
-MarkupSafe==1.1.1
-packaging==20.3
-Pygments==2.7.4
-pyparsing==2.4.6
-pytz==2019.3
-requests==2.23.0
-six==1.14.0
-snowballstemmer==2.0.0
-Sphinx==2.4.4
-sphinx-rtd-theme==0.4.3
-sphinxcontrib-applehelp==1.0.2
-sphinxcontrib-devhelp==1.0.2
-sphinxcontrib-htmlhelp==1.0.3
-sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-qthelp==1.0.3
-sphinxcontrib-serializinghtml==1.1.4
-urllib3==1.26.5
+Sphinx>=5.0.2
+sphinx-autobuild
+sphinx-reredirects>=0.1.2
+sphinx-rtd-theme>=1.0.0
+sphinx-rtd-dark-mode>=1.3.0
+doc8>=0.11.2
+jinja2
+markupSafe
+sphinx-copybutton

docs/scripts/doc8_style_check.sh

@@ -2,4 +2,4 @@
 # halt script on error
 set -e
 # Check for Style Code Violations
-doc8 --max-line-length 100 ./docs/source --ignore D000 --quiet
+doc8 --max-line-length 100 source --ignore D000 --quiet

docs/scripts/sphinx_build_link_check.sh

@@ -2,4 +2,4 @@
 # halt script on error
 set -e
 # Build locally, and then check links
-sphinx-build -E -W -b linkcheck ./docs/source ./docs/build
+sphinx-build -E -W -b linkcheck source build