diff --git a/docs/Makefile b/docs/Makefile index 649b9e371a3..4eeef58cf35 100644 --- a/docs/Makefile +++ b/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 diff --git a/docs/make.bat b/docs/make.bat index 6247f7e2317..4a3c1a48527 100644 --- a/docs/make.bat +++ b/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% diff --git a/docs/source/conf.py b/docs/source/conf.py index 069309ad7ac..f4e4527eb99 100644 --- a/docs/source/conf.py +++ b/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), } diff --git a/docs/source/reference/license-detection-reference.rst b/docs/source/reference/license-detection-reference.rst index a0c1e3025fa..62bbbe65ec3 100644 --- a/docs/source/reference/license-detection-reference.rst +++ b/docs/source/reference/license-detection-reference.rst @@ -30,6 +30,8 @@ implemented: Some other elements are still WIP, see `issue #3300 `_ for more details on this. +.. _what-is-a-licensedetection: + What is a LicenseDetection? --------------------------- diff --git a/docs/source/tutorials/how_to_visualize_scan_results.rst b/docs/source/tutorials/how_to_visualize_scan_results.rst index ef26041e302..f88b5b108ab 100644 --- a/docs/source/tutorials/how_to_visualize_scan_results.rst +++ b/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 `_ 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 `_. - .. - [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 `_ here. - -You can also run the following commands:: - - sudo apt-get install -y nodejs - sudo npm install npm@5.2.0 -g - -After ``Node.js`` and ``npm`` is installed and get the Scancode Workbench 3.1.0 tarball from the -`Workbench Release Page `_. 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 ``, 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 diff --git a/setup-mini.cfg b/setup-mini.cfg index 36518fe4548..fd465ecbf76 100644 --- a/setup-mini.cfg +++ b/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 = diff --git a/setup.cfg b/setup.cfg index 1ed58fe9953..7fc938a2e32 100644 --- a/setup.cfg +++ b/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 =