Added docs server script, dark mode & copybutton for docs (aboutcode-…

…org#3549)

* Added docs server script, dark mode & copybutton for docs

Signed-off-by: Omkar Phansopkar <[email protected]>

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/make.bat

@@ -7,11 +7,16 @@ 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.
@@ -28,6 +33,13 @@ if errorlevel 9009 (
 %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%
 

docs/source/conf.py

@@ -29,8 +29,13 @@
 extensions = [
     "sphinx.ext.intersphinx",
     "sphinx_reredirects",
+    'sphinx_rtd_theme',
+    "sphinx_rtd_dark_mode",
+    "sphinx.ext.extlinks",
+    "sphinx_copybutton",
 ]
 
+default_dark_mode = False
 
 # Redirects for olds pages
 # See https://documatt.gitlab.io/sphinx-reredirects/usage.html
@@ -46,7 +51,7 @@
 
 intersphinx_mapping = {
     "aboutcode": ("https://aboutcode.readthedocs.io/en/latest/", None),
-    "scancode-workbench": ("https://scancode-workbench.readthedocs.io/en/develop/", None),
+    "scancode-workbench": ("https://scancode-workbench.readthedocs.io/en/latest/", None),
 }
 
 

docs/source/reference/license-detection-reference.rst

@@ -30,6 +30,8 @@ implemented:
 
 Some other elements are still WIP, see `issue #3300 <https://github.com/nexB/scancode-toolkit/issues/3300>`_ for more details on this.
 
+.. _what-is-a-licensedetection:
+
 What is a LicenseDetection?
 ---------------------------
 

docs/source/tutorials/how_to_visualize_scan_results.rst

@@ -3,109 +3,14 @@
 How to Visualize Scan results
 =============================
 
-In this simple tutorial example, we import results from a basic scan performed on the ``samples``
-directory distributed by default with Scancode, and visualize the outputs through
-Scancode Workbench.
+To help visualize the scans, we have a dedicated tool  `Scancode workbench <https://github.com/nexb/scancode-workbench/>`_  which is a desktop application that allows you to visualize and explore the results of one or more scans. It is a cross-platform application that runs on Windows, Mac OS X and Linux. It is built using the Electron framework and is built using Electron, Typescript & React
+
+Detailed Installation and Usage guide can be found here -  :ref:`scancode-workbench:getting-started`
 
 .. WARNING::
 
-    This tutorial uses the 3.1.1 version of Scancode Toolkit, and Scancode Workbench 3.1.0 (This
-    beta version of ScanCode Workbench is compatible with scans from any ScanCode Toolkit develop
-    version/branch at or after v3.0.2). If you are using an older version of Scancode Toolkit, check
+    This tutorial uses the 32.x version of Scancode Toolkit, and Scancode Workbench 4.0.x (This version of ScanCode Workbench is compatible with scans from any ScanCode Toolkit develop
+    version/branch at or after v32.x). If you are using an older version of Scancode Toolkit, check
     respective versions of this documentation. Also refer the Scancode Workbench
     `release highlights <https://github.com/nexB/scancode-workbench/releases/>`_.
-
 ..
-    [ToDo]
-    Add Windows/MacOS Support and remove this WARNING.
-
-.. WARNING::
-
-    This tutorial is for Linux based systems presently. Additional Help for Windows/MacOS will be
-    added.
-
-Setting up Scancode Workbench
------------------------------
-
-According to the Installation instructions for the Workbench, we have to install Node.js 6.x or later.
-Refer to Node.js install `instructions <https://nodejs.org/en/download/package-manager/>`_ here.
-
-You can also run the following commands::
-
-    sudo apt-get install -y nodejs
-    sudo npm install [email protected] -g
-
-After ``Node.js`` and ``npm`` is installed and get the Scancode Workbench 3.1.0 tarball from the
-`Workbench Release Page <https://github.com/nexB/scancode-workbench/releases/tag/v3.1.0>`_. Extract
-the package and then launch Scancode Workbench::
-
-    ./ScanCode-Workbench
-
-This opens the Workbench.
-
-.. note::
-
-    You can also build Scancode Toolkit and Scancode Workbench from source. Clone the repository,
-    don't forget to checkout to the specific release using ``git checkout <release>``, and follow
-    the build instructions. You will ll also have to create a Python virtual environment.
-
-
-
-Importing Data into Scancode Workbench
---------------------------------------
-
-#. Click on the ``File -> Import JSON File`` or Press ``Ctrl + I``.
-
-#. Select the file from the pop-up window.
-
-#. Select a Name and Location (where you want it later) for the .sqlite output file.
-
-.. note::
-
-    You can also import a .sqlite file you've saved in the past to load scan results. As it is much
-    faster, once you've imported the JSON file and a corresponding SQLite file has been created,
-    you shouldn't repeat this. Instead, import the SQLite file next time you want to visualize the
-    same scan result.
-
-Visualization
--------------
-
-Views
-^^^^^
-
-Refer to the workbench documentation for more information on Visualization.
-
-The dashboard has a general overview.
-
-.. image::  /tutorials/data/workbench_dashboard.png
-
-There are three main views (They appear in the same order in the GIFs):
-
-- Chart Summary View,
-- Table View,
-- Components Summary View.
-
-.. image::  /tutorials/data/views_sample.gif
-
-Filters
-^^^^^^^
-
-You can also click any file/directory on the file list located on the right, to filter the results
-such that it only contains results from that File/Directory.
-
-.. image::  /tutorials/data/filter_sample.gif
-
-Components
-^^^^^^^^^^
-
-Refer :ref:`workbench_components` for more information on Components.
-
-In the table view,
-
-#. Apply filters by selecting Files/Directories
-#. Right Click on the Left Panel
-#. Select ``Edit Component``
-#. A pop-up opens with fields, make necessary edits and Save.
-#. Go to the Component Summary View to see the Component.
-
-.. image::  /tutorials/data/components_sample.gif

setup-mini.cfg

@@ -141,6 +141,9 @@ docs =
     sphinx_rtd_theme >= 0.5.1
     sphinx-reredirects >= 0.1.2
     doc8 >= 0.8.1
+    sphinx-autobuild
+    sphinx-rtd-dark-mode>=1.3.0
+    sphinx-copybutton
 
 # linux-only package handling
 packages =

setup.cfg

@@ -141,6 +141,9 @@ docs =
     sphinx_rtd_theme >= 0.5.1
     sphinx-reredirects >= 0.1.2
     doc8 >= 0.8.1
+    sphinx-autobuild
+    sphinx-rtd-dark-mode>=1.3.0
+    sphinx-copybutton
 
 # linux-only package handling
 packages =