aboutcode-org · steven-esser · Apr 2, 2020 · Mar 26, 2020 · Mar 27, 2020 · Mar 28, 2020
diff --git a/NOTICE b/NOTICE
@@ -1,7 +1,7 @@
 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.

diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css
@@ -136,3 +136,49 @@ code, .rst-content tt, .rst-content code {
     margin-bottom: 0px;
     line-height: 24px;
 }
+
+.with-border {
+    border: solid 1px #cccccc;
+}
+
+/* this is used by the genindex added via layout.html (see source/_templates/) to sidebar toc */
+.reference.internal.toc-index {
+    color: #d9d9d9;
+}
+
+.reference.internal.toc-index.current {
+    background-color: #ffffff;
+    color: #000000;
+    font-weight: bold;
+}
+
+.toc-index-div {
+    border-top: solid 1px #666666;
+    margin-top: 10px;
+    padding-top: 10px;
+}
+
+/* The next 2 fix the poor vertical spacing in genindex.html (the alphabetized index) */
+.indextable.genindextable {
+    margin-bottom: 20px;
+}
+
+div.genindex-jumpbox {
+    margin-bottom: 20px;
+}
+
+/* This applies to a 'figure' -- an 'image' with 'caption' and optional 'legend' */
+/* See, e.g., https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure */
+.legend p {
+    font-size: 14px;
+    margin-bottom: 0px;
+    padding-bottom: 0px;
+    color: #000000;
+    font-style: italic;
+}
+
+/* inserting figure into bulleted list has 0 margin at top and too much (24px) at bottom */
+.rst-content div.figure {
+    margin-top: 10px;
+    margin-bottom: 5px;
+}
diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html
@@ -0,0 +1,8 @@
+{% extends "!layout.html" %}
+
+  {% block menu %}
+    {{ super() }}
+    <div class="toc-index-div">
+    <a href="{{pathto('genindex.html', 1)}}" class="reference internal toc-index">Index</a>
+    </div>
+  {% endblock %}
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -73,5 +73,17 @@
     "conf_py_path": "/docs/source/",  # path in the checkout to the docs root
     }
 
+# If false, no index is generated.
+#
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#
+# html_show_sourcelink = True
+
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-html_show_sphinx = False
+html_show_sphinx = True
diff --git a/docs/source/contribute/building.rst b/docs/source/contribute/building.rst
@@ -1,8 +1,8 @@
 .. _building:
 
-========
-Building
-========
+=================
+:index:`Building`
+=================
 
 Clone, Install, Build and Run
 =============================

diff --git a/docs/source/contribute/support.rst → .../source/contribute/community-channels.rst b/docs/source/contribute/support.rst → .../source/contribute/community-channels.rst
@@ -1,7 +1,9 @@
-=======
-Support
-=======
+===========================
+:index:`Community Channels`
+===========================
 
 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
+
+:guilabel:`[more to come]`
diff --git a/docs/source/contribute/contributing-code.rst b/docs/source/contribute/contributing-code.rst
@@ -0,0 +1,5 @@
+==========================
+:index:`Contributing Code`
+==========================
+
+:guilabel:`[to come]`
diff --git a/docs/source/contribute/index.rst b/docs/source/contribute/index.rst
@@ -1,6 +1,8 @@
-==========
-Contribute
-==========
+.. _contribute:
+
+===================
+:index:`Contribute`
+===================
 
 :guilabel:`[Intro to come.]`
 
@@ -9,4 +11,6 @@ Contribute
 
    building
    testing
-   support
+   reporting-issues
+   contributing-code
+   community-channels
diff --git a/docs/source/contribute/reporting-issues.rst b/docs/source/contribute/reporting-issues.rst
@@ -0,0 +1,5 @@
+=========================
+:index:`Reporting Issues`
+=========================
+
+:guilabel:`[to come]`
diff --git a/docs/source/contribute/testing.rst b/docs/source/contribute/testing.rst
@@ -1,6 +1,6 @@
-=======
-Testing
-=======
+================
+:index:`Testing`
+================
 
 Test ABCM functionality using:
 

diff --git a/docs/source/getting-started/data/initial_load_getting_started.png b/docs/source/getting-started/data/initial_load_getting_started.png
diff --git a/docs/source/getting-started/index.rst b/docs/source/getting-started/index.rst
@@ -1,38 +1,64 @@
-===============
-Getting Started
-===============
+.. _getting-started:
 
-:guilabel:`[Intro to come.]`
+========================
+:index:`Getting Started`
+========================
 
-.. Note:: This is from the GH README -- have only made minor changes -- needs to be updated and expanded.
+Download and Install
+=======================
 
+-  You can download the latest ScanCode Workbench release for your Windows, OS X or Linux
+   operating system from the `ScanCode Workbench releases page <https://github.com/nexB/scancode-workbench/releases>`__.
+   Once downloaded, you'll find the ScanCode Workbench executable in the
+   ``ScanCode-Workbench-<os>-x64-<version>`` folder.
+   On Windows 10, for example, the executable will be named `ScanCode-Workbench.exe`.
 
-Download Latest Release
-=======================
+-  If you're interested in digging into the code, you can also use ScanCode Workbench by cloning
+   the GitHub repository and building it yourself -- see the :ref:`Contribute/Building<building>`
+   section for details.
 
--  You can `download the latest release <https://github.com/nexB/scancode-workbench/releases>`__
-   for your operating system or build it yourself (see the :ref:`building` section for details).
+ScanCode Workbench-ScanCode Toolkit Compatibility
+=================================================
 
--  Once downloaded, you can find ScanCode-Workbench under
-   ``dist/ScanCode-Workbench-<os>-x64-<version>``.
+-  ScanCode Workbench >= v3.1.1 is only compatible with scans from ScanCode v3.1.1 and above
+   that have been run with the ScanCode Toolkit ``-i`` option.
 
--  ScanCode Workbench >= v2 is only compatible with scans from ScanCode v2.0.0 and above
-   which are run with the ScanCode ``-i`` option. (For a list of available ScanCode Toolkit options
-   see the ScanCode Toolkit documentation:
-   :doc:`scancode-toolkit:tutorials/how_to_set_what_will_be_detected_in_a_scan`.
+   -  A list of available ScanCode Toolkit options is available in the ScanCode Toolkit
+      documentation:
+      :doc:`scancode-toolkit:tutorials/how_to_set_what_will_be_detected_in_a_scan`.
 
-Import a Sample Scan
-====================
+Open ScanCode Workbench and Load a ScanCode Toolkit Scan
+========================================================
+
+-  Double-click the ScanCode Workbench executable you downloaded.  You'll probably want to
+   maximize the application once it has opened.
+
+-  Import your JSON scan file and save it as a SQLite file (ScanCode Workbench works with the
+   data in a SQLite database).
+
+   -  :kbd:`File` > :kbd:`Import JSON File` (:kbd:`Ctrl` + :kbd:`I`) ==> opens
+      ``Open a JSON File`` window.
 
-We have provided a set of sample scans that you can quickly review in ScanCode Workbench in
-order to get a sense of its functionality and the types of information captured by a scan.
+   -  Select your JSON scan and click :kbd:`Open` ==> opens ``Save a SQLite Database File`` window.
 
-The samples are located at https://github.com/nexB/scancode-workbench/tree/develop/samples.
+   -  Keep or modify the default SQLite filename and click :kbd:`Save`.
 
-Import a ScanCode Toolkit Scan of Your Own Code
-===============================================
+-  You're now looking at your scan data displayed in the Table View -- the Table View itself is on
+   the right, and the Directory Tree (which is visible in all views) is on the left.
 
-Import a ScanCode JSON file, and see what components are in your software!
+   .. figure:: data/initial_load_getting_started.png
+      :class: with-border
+      :width: 600px
+
+      ..
+
+      Your first imported ScanCode Toolkit Scan.
+
+You can find additional details in the :ref:`how-to-guides` section below.
+
+Try a Sample Scan
+====================
 
-If you're ready, keep on reading this documentation for more information on how to use
-ScanCode Workbench.
+We've also provided a set of `sample scans <https://github.com/nexB/scancode-workbench/tree/develop/samples>`__
+that you can  review in ScanCode Workbench in order to get a sense of its functionality and the
+types of information captured by a scan.
diff --git a/...urce/how-to-guides/create-conclusions.rst → ...create-conclusions/create-conclusions.rst b/...urce/how-to-guides/create-conclusions.rst → ...create-conclusions/create-conclusions.rst
@@ -1,8 +1,8 @@
 .. _workbench_components:
 
-==========================
-How-To: Create Conclusions
-==========================
+===================================
+:index:`How-To: Create Conclusions`
+===================================
 
 A Conclusion in ScanCode Workbench refers to the documentation of your analysis and conclusions
 about the name, version, owner, copyright, license expression and other attributes for a single

diff --git a/...how-to-guides/data/conclusion-form-01.png → ...e-conclusions/data/conclusion-form-01.png b/...how-to-guides/data/conclusion-form-01.png → ...e-conclusions/data/conclusion-form-01.png
diff --git a/...e/how-to-guides/data/scandatatable-01.png → ...ate-conclusions/data/scandatatable-01.png b/...e/how-to-guides/data/scandatatable-01.png → ...ate-conclusions/data/scandatatable-01.png
diff --git a/docs/source/how-to-guides/create-conclusions/index.rst b/docs/source/how-to-guides/create-conclusions/index.rst
@@ -0,0 +1,8 @@
+===========================
+:index:`Create Conclusions`
+===========================
+
+.. toctree::
+   :maxdepth: 3
+
+   create-conclusions
diff --git a/...ancode-workbench-chart-summary-filter.gif → ...ancode-workbench-chart-summary-filter.gif b/...ancode-workbench-chart-summary-filter.gif → ...ancode-workbench-chart-summary-filter.gif
diff --git a/...data/scancode-workbench-chart-summary.gif → ...data/scancode-workbench-chart-summary.gif b/...data/scancode-workbench-chart-summary.gif → ...data/scancode-workbench-chart-summary.gif
diff --git a/docs/source/how-to-guides/explore-your-data/index.rst b/docs/source/how-to-guides/explore-your-data/index.rst
@@ -0,0 +1,10 @@
+==========================
+:index:`Explore Your Data`
+==========================
+
+.. toctree::
+   :maxdepth: 3
+
+   navigate-chart-summary-view
+
+:guilabel:`[to come]`
diff --git a/...to-guides/navigate-chart-summary-view.rst → ...your-data/navigate-chart-summary-view.rst b/...to-guides/navigate-chart-summary-view.rst → ...your-data/navigate-chart-summary-view.rst
@@ -1,6 +1,6 @@
-=======================================
-How-To: Navigate the Chart Summary View
-=======================================
+================================================
+:index:`How-To: Navigate the Chart Summary View`
+================================================
 
 Display the view
 ================

diff --git a/docs/source/how-to-guides/export-json-records/index.rst b/docs/source/how-to-guides/export-json-records/index.rst
@@ -0,0 +1,13 @@
+============================
+:index:`Export JSON Records`
+============================
+
+Export a JSON file
+==================
+
+* To export a JSON file:
+
+  * Select the :kbd:`File` menu and then select :kbd:`Export JSON File` (keyboard shortcut:
+    :kbd:`Ctrl+E` or :kbd:`⌘+E`).
+  * In the dialog window that opens, add a name for the file, navigate to the directory in which
+    you want to save the file and click :kbd:`Save`.
diff --git a/docs/source/how-to-guides/import-export-json.rst b/docs/source/how-to-guides/import-export-json.rst
diff --git a/docs/source/how-to-guides/index.rst b/docs/source/how-to-guides/index.rst
@@ -1,15 +1,24 @@
-=============
-How-To Guides
-=============
+.. _how-to-guides:
 
-:guilabel:`[Intro to come.]`
+======================
+:index:`How-To Guides`
+======================
+
+The ScanCode Workbench How-To Guides will walk you through loading and analyzing
+a ``-clipeu`` scan of ``e2fsprogs-1.45.6.tar.gz``.
+
+.. Note:: If you'd like to follow along, you can download a copy of the ``e2fsprogs-1.45.6``
+   package from `SourceForge <https://sourceforge.net/projects/e2fsprogs/files/e2fsprogs/v1.45.6/>`__,
+   run a ``-clipeu`` scan with `ScanCode Toolkit <https://github.com/nexB/scancode-toolkit>`__,
+   load the ``.json`` output into ScanCode Workbench and work your way through the How-To Guides.
 
 .. toctree::
    :maxdepth: 3
 
-   check-for-errors
-   import-export-json
-   open-save-sqlite-file
-   create-conclusions
-   license-policy-support
-   navigate-chart-summary-view
+   load-your-data/index
+   lookup-scan-version/index
+   explore-your-data/index
+   create-conclusions/index
+   export-json-records/index
+   troubleshooting/index
+   special-topics/index
diff --git a/docs/source/how-to-guides/load-your-data/data/creating-database.png b/docs/source/how-to-guides/load-your-data/data/creating-database.png
diff --git a/docs/source/how-to-guides/load-your-data/data/import-json-cropped.png b/docs/source/how-to-guides/load-your-data/data/import-json-cropped.png
diff --git a/...e/how-to-guides/data/import-json-file.gif → .../load-your-data/data/import-json-file.gif b/...e/how-to-guides/data/import-json-file.gif → .../load-your-data/data/import-json-file.gif
diff --git a/docs/source/how-to-guides/load-your-data/data/import-json.png b/docs/source/how-to-guides/load-your-data/data/import-json.png
diff --git a/docs/source/how-to-guides/load-your-data/data/initial_load.png b/docs/source/how-to-guides/load-your-data/data/initial_load.png
diff --git a/docs/source/how-to-guides/load-your-data/data/open-sqlite-cropped.png b/docs/source/how-to-guides/load-your-data/data/open-sqlite-cropped.png
diff --git a/docs/source/how-to-guides/load-your-data/data/open-sqlite.png b/docs/source/how-to-guides/load-your-data/data/open-sqlite.png
diff --git a/docs/source/how-to-guides/load-your-data/data/save-as-sqlite-cropped.png b/docs/source/how-to-guides/load-your-data/data/save-as-sqlite-cropped.png
diff --git a/docs/source/how-to-guides/load-your-data/data/save-as-sqlite.png b/docs/source/how-to-guides/load-your-data/data/save-as-sqlite.png