Add source-controlled documentation

* Migrate workbench docs from aboutcode.readthedocs.org
* Add CI doc checks for Travis CI

Addresses: #411

Signed-off-by: Steven Esser <sesser@nexb.com>

.gitignore

@@ -16,6 +16,7 @@
 /local
 node_modules/
 bower_components/
+docs/build
 
 # Installer logs
 debug.log
@@ -31,6 +32,7 @@ npm-debug.log
 .*.sw[po]
 .build
 .ve
+.venv
 *.bak
 /.cache/
 

.travis.yml

@@ -1,36 +1,55 @@
-language: node_js
-sudo: required
-dist: xenial
-
-node_js:
-  - "10"
-
-env:
-  global:
-    - CC=clang CXX=clang++ npm_config_clang=1
-
 matrix:
-    include:
-        - os: linux
-          python: 2.7.13
-        - os: osx
-          language: generic
-          osx_image: xcode11
-
-
-before_install:
-  - if [ $TRAVIS_OS_NAME = linux ]; then sudo apt-get update; sudo apt-get install build-essential -y; fi
-  - node --version
-  - npm --version
-  - openssl version
-  - python --version
-  - ssh -V
-  - pip -V
-
-script:
-  - npm install
-  - npm test
-  - python build.py
+  include:
+    - os: linux
+      dist: xenial
+      sudo: required
+      language: node_js
+      node_js: 10
+      python: 2.7.13
+      env:
+        - CC=clang
+        - CXX=clang++
+        - npm_config_clang=1
+      script:
+        - sudo apt install build-essential -y
+        - npm install
+        - npm test
+        - python build.py
+
+    - os: macos
+      sudo: required
+      language: generic
+      osx_image: xcode11
+      env:
+        - CC=clang
+        - CXX=clang++
+        - npm_config_clang=1
+      script:
+        - npm install
+        - npm test
+        - python build.py
+
+    - os: linux
+      dist: xenial
+      python: 2.7.13
+      sudo: required
+      script:
+        - sudo pip install Sphinx sphinx_rtd_theme doc8
+        - chmod +x ./docs/scripts/sphinx_build_link_check.sh
+        - chmod +x ./docs/scripts/doc8_style_check.sh
+        - "./docs/scripts/sphinx_build_link_check.sh"
+        - "./docs/scripts/doc8_style_check.sh"
+
+    - os: linux
+      dist: xenial
+      python: 3.6
+      sudo: required
+      script:
+        - sudo pip install Sphinx sphinx_rtd_theme doc8
+        - chmod +x ./docs/scripts/sphinx_build_link_check.sh
+        - chmod +x ./docs/scripts/doc8_style_check.sh
+        - "./docs/scripts/sphinx_build_link_check.sh"
+        - "./docs/scripts/doc8_style_check.sh"
 
 
 addons:

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@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

docs/requirements.txt

@@ -0,0 +1,30 @@
+alabaster==0.7.12
+Babel==2.7.0
+certifi==2019.11.28
+chardet==3.0.4
+doc8==0.8.0
+docutils==0.15.2
+idna==2.8
+imagesize==1.1.0
+Jinja2==2.10.3
+MarkupSafe==1.1.1
+packaging==19.2
+pbr==5.4.4
+pkg-resources==0.0.0
+Pygments==2.5.2
+pyparsing==2.4.5
+pytz==2019.3
+requests==2.22.0
+restructuredtext-lint==1.3.0
+six==1.13.0
+snowballstemmer==2.0.0
+Sphinx==2.2.2
+sphinx-rtd-theme==0.4.3
+sphinxcontrib-applehelp==1.0.1
+sphinxcontrib-devhelp==1.0.1
+sphinxcontrib-htmlhelp==1.0.2
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.2
+sphinxcontrib-serializinghtml==1.1.3
+stevedore==1.31.0
+urllib3==1.25.7

docs/scripts/doc8_style_check.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+# halt script on error
+set -e
+# Check for Style Code Violations
+doc8 --max-line-length 100 ./docs/source --ignore D000 --quiet

docs/scripts/sphinx_build_link_check.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+# halt script on error
+set -e
+# Build locally, and then check links
+sphinx-build -E -W -b linkcheck ./docs/source ./docs/build

docs/source/basics/building.rst

@@ -0,0 +1,42 @@
+.. _workbench_requirements:
+
+Building Requirements
+=====================
+
+Linux
+-----
+
+- Python 2.7
+- `Node.js version <https://nodejs.org/en/download/package-manager/>`_ 6.x or later
+- npm 3.10.x or later but <= 5.2.0 (run ``npm install npm@5.2.0 -g``)
+
+MacOS
+-----
+
+- Python 2.7
+- `Node.js <https://nodejs.org/en/>`_ >=6.x or later but <=8.9.4
+- npm 3.10.x or later but <= 5.2.0 (run ``npm install npm@5.2.0 -g``)
+- Command Line Tools for `Xcode <https://developer.apple.com/xcode/downloads/>`_
+  (run ``xcode-select --install to install``)
+
+Windows
+-------
+
+- `Node.js <https://nodejs.org/en/>`_ 6.x or later
+- npm 3.10.x or later but <= 5.2.0 (``run npm install npm@5.2.0 -g``)
+- Python v2.7.x
+
+  * 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.
+
+- Visual C++ Build Environment:
+
+  * Either:
+
+  - Option 1: Install `Visual C++ Build Tools 2015 <https://www.microsoft.com/en-in/download/details.aspx?id=48159>`_
+    (or modify an existing installation) and select Common Tools for Visual C++ during setup.
+    This also works with the free Community and Express for Desktop editions.
+  - Option 2: `Visual Studio 2015 <https://visualstudio.microsoft.com/vs/older-downloads/>`_ (Community Edition or better)
+
+  * Note: Windows 7 requires `.NET Framework 4.5.1 <http://www.microsoft.com/en-us/download/details.aspx?id=40773>`_
+  * Launch cmd, ``npm config set msvs_version 2015``

docs/source/basics/check_for_errors_in_the_developer_tools.rst

@@ -0,0 +1,14 @@
+Check for Errors in the Developer Tools
+=======================================
+
+When an unexpected error occurs in ScanCode Workbench, you will normally see a dialog message which
+provides details about the error and allows you to create an issue.
+
+.. image:: data/dialog-error.png
+    :scale: 50 %
+
+If you can reproduce the error, use this approach to get the stack trace and report the issue. Open
+the Developer Tools with ``Ctrl+Shift+I`` or ``Alt+Cmd+I``. From there, click the Console tab.
+Include the error that is logged in the issue in a code block or a file attachment.
+
+.. image:: data/developer-tools-error.png

docs/source/basics/index.rst

@@ -0,0 +1,10 @@
+Basics
+======
+
+.. toctree::
+   :maxdepth: 3
+
+   scancode_workbench_views
+   building
+   platform_support
+   check_for_errors_in_the_developer_tools

docs/source/basics/platform_support.rst

@@ -0,0 +1,84 @@
+ScanCode Workbench Platform Support
+===================================
+
+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 SP1    |    x64  |     1      |                                         |
++-------------+------------------+---------+------------+-----------------------------------------+
+|  Windows    | Windows 10 SP?   |    x64  |     2      |                                         |
++-------------+------------------+---------+------------+-----------------------------------------+
+|  MacOS      | 10.9 Mavericks   |    x64  |     1      |                                         |
++-------------+------------------+---------+------------+-----------------------------------------+
+|  MacOS      | 10.10 Yosemite   |    x64  |     2      |                                         |
++-------------+------------------+---------+------------+-----------------------------------------+
+|  MacOS      | 10.11 El Capitan |    x64  |     2      |                                         |
++-------------+------------------+---------+------------+-----------------------------------------+
+|  MacOS      | 10.12 Sierra     |    x64  |     2      |                                         |
++-------------+------------------+---------+------------+-----------------------------------------+
+| Linux Deb   | Ubuntu 12.04     |    x64  |     1      | 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  |     2      | 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
+^^^^^
+
+Only 64-bit binaries 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

docs/source/basics/scancode_workbench_views.rst

@@ -0,0 +1,40 @@
+.. _workbench_views:
+
+Scancode Workbench Views
+========================
+
+Directory Tree
+--------------
+
+An interactive directory tree is always present on the left side of the application. The tree is
+expandable and collapsible. This allows the user to navigate the codebase structure. If a directory
+is selected, only that directory and its sub-files and folders will be shown in the view.
+Similarly, if a single file is selected, only information for that selected file will be shown.
+
+.. image:: data/navigate-code-tree.gif
+
+Table View
+----------
+
+In the table view, the available clues detected by `ScanCode <https://github.com/nexB/scancode-toolkit/>`_
+are shown in a tabular format. A user can see provenance clues such as license and copyright
+information detected by ScanCode. A user can also see the file information (e.g. file type,
+file size, etc) and package information (package type, primary language of package) that was
+detected. The columns can be sorted as well as shown or hidden based on what the user’s
+preferences. Searching for specific clues (license names, copyrights, etc.) is also available in
+this view.
+
+.. image:: data/table-view.gif
+
+Chart Summary View
+------------------
+
+With the chart summary view, a user can select a node in the directory tree (i.e., a directory,
+folder or file) and display a horizontal bar chart listing the values identified in the scanned
+codebase -- that is, the clues detected by ScanCode Toolkit -- for a number of different
+attributes. The attributes are a subset of the columns displayed in the table view, and can be
+selected by clicking the dropdown at the top of the view. The chart displays the full range of
+values for the selected directory tree node and attribute and the number of times each value occurs
+in the scanned codebase.
+
+.. image:: data/scancode-workbench-chart-summary.gif