diff --git a/docs/.gitignore b/docs/.gitignore index dc3f9d59..887f56e8 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,5 +1,5 @@ # Virtual environment -.venv/ +venv/ # sphinx build folder build/ diff --git a/docs/README.md b/docs/README.md index 8c7e0dfc..7ec09b2c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,8 +2,8 @@ The first step you want to do is create the python virtual environment: ``` $ cd docs/ -$ python3 -m venv .venv -$ source .venv/bin/activate +$ python3 -m venv venv +$ source venv/bin/activate $ pip install -r requirements.txt ``` diff --git a/docs/requirements.txt b/docs/requirements.txt index 2275b07e..c338e5eb 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,7 +1,7 @@ -Sphinx>=7.0.0 +Sphinx>=5.0.2 +sphinx-rtd-theme>=1.0.0 +sphinx-reredirects >= 0.1.2 +doc8>=0.11.2 sphinx-autobuild -sphinx-rtd-theme -sphinx-reredirects -doc8 jinja2 -markupSafe \ No newline at end of file +markupSafe diff --git a/docs/source/contribute/building.rst b/docs/source/contribute/building.rst index b40de20c..f8e6f572 100644 --- a/docs/source/contribute/building.rst +++ b/docs/source/contribute/building.rst @@ -30,7 +30,7 @@ Linux ----- - Python 3.7 or later -- `Node.js `_ 12.x or later +- `Node.js `__ 12.x or later - npm 6.14.x or later - For CentOS (or linux distros without the new libstdc++) - @@ -46,7 +46,7 @@ MacOS ----- - Python 3.7 or later -- `Node.js `_ 12.x or later +- `Node.js `__ 12.x or later - npm 6.14.x or later - Command Line Tools for `Xcode `_ (run ``xcode-select --install`` to install) @@ -55,7 +55,7 @@ Windows ------- - Python v3.7 or later -- `Node.js `_ 12.x or later +- `Node.js `__ 12.x or later - npm 6.14.x or later * Make sure your Python path is set. To verify, open a command prompt and type @@ -76,3 +76,30 @@ After building is done, you can find ScanCode-Workbench under are also built. .. Note:: A build for any of the three target platforms must be executed on the targeted platform. + +Building Documentation +====================== + +Create python environment, make docs + + +.. code-block:: none + + # Clone this repository + $ git clone https://github.com/nexB/scancode-workbench.git + + # Go into the docs directory + $ cd docs/ + + # Setup virtual environment for python dependencies + $ python3 -m venv venv + $ source venv/bin/activate + + # Install dependencies + $ pip install -r requirements.txt + + # Build Documentation + $ make html + + # Run Documentation server in dev mode + $ make dev diff --git a/docs/source/how-to-guides/explore-your-data/navigate-chart-summary-view.rst b/docs/source/how-to-guides/explore-your-data/navigate-chart-summary-view.rst index 44574efe..2137f26b 100644 --- a/docs/source/how-to-guides/explore-your-data/navigate-chart-summary-view.rst +++ b/docs/source/how-to-guides/explore-your-data/navigate-chart-summary-view.rst @@ -3,7 +3,7 @@ ================================================ Display the Chart Summary view -================ +==================================== Once you have a SQLite file loaded into ScanCode Workbench, displaying the Chart Summary View is easy: diff --git a/docs/source/how-to-guides/explore-your-data/navigate-license-explorer.rst b/docs/source/how-to-guides/explore-your-data/navigate-license-explorer.rst index 4b31fbfe..0d70527c 100644 --- a/docs/source/how-to-guides/explore-your-data/navigate-license-explorer.rst +++ b/docs/source/how-to-guides/explore-your-data/navigate-license-explorer.rst @@ -1,9 +1,9 @@ -================================================ +==================================================== :index:`How-To: Navigate the License Explorer View` -================================================ +==================================================== Display the License Explorer view -================ +=================================== Once you have a SQLite file loaded into ScanCode Workbench, @@ -24,7 +24,7 @@ You can search for any license detecttion / clue by typing in the search box on .. figure:: data/license-explorer-search.gif Matches & File regions table -==================== +=================================== For the selected license, you can view the matches resulting into the detection and the file regions where the license was detected. You can click on the data file path to view that path in Tableview diff --git a/docs/source/how-to-guides/explore-your-data/navigate-package-explorer.rst b/docs/source/how-to-guides/explore-your-data/navigate-package-explorer.rst index fe5f0677..80c83fa5 100644 --- a/docs/source/how-to-guides/explore-your-data/navigate-package-explorer.rst +++ b/docs/source/how-to-guides/explore-your-data/navigate-package-explorer.rst @@ -1,16 +1,16 @@ -================================================ +==================================================== :index:`How-To: Navigate the Package Explorer View` -================================================ +==================================================== Display the Package Explorer view -================ +=================================== Once you have a SQLite file loaded into ScanCode Workbench, * Click on `Package Explorer` in the sidebar or open the :kbd:`View` menu and select :kbd:`Package Explorer` Select a Package or Dependency -========================= +==================================== On the left pane, Packages are shown in a hierarchical manner as `Package Type` > `Package` > `Dependencies` Upon selecting a Package / Dependency, details of the entire entity is shown on the right. @@ -30,7 +30,7 @@ You can filter the packages / dependencies by their data sources and/or dependen .. figure:: data/package-explorer-filter.gif Dependencies table -==================== +======================== When a package is selected, the dependencies for that package are shown in a table in the details pane showing Dependency information like `PURL, Scope, Data source ID, etc` diff --git a/docs/source/how-to-guides/explore-your-data/navigate-tableview.rst b/docs/source/how-to-guides/explore-your-data/navigate-tableview.rst index 152083c0..4a177891 100644 --- a/docs/source/how-to-guides/explore-your-data/navigate-tableview.rst +++ b/docs/source/how-to-guides/explore-your-data/navigate-tableview.rst @@ -3,7 +3,7 @@ ================================================ Display the Table view -================ +============================ Once you have a SQLite file loaded into ScanCode Workbench, you're automatically redirected to the Tableview. To navigate to Tableview from other views you can click on `Table View` in the sidebar or open the :kbd:`View` menu and select :kbd:`Table View` @@ -12,7 +12,7 @@ To navigate to Tableview from other views you can click on `Table View` in the s Select a path -=================== +======================== You can collapse/expand the FileTree on the left and select a file/directory. Only the files under this path will be visible in the tableview @@ -20,7 +20,7 @@ You can collapse/expand the FileTree on the left and select a file/directory. On Select Preset columns -==================== +========================== You can select one of the available column groups, grouped based on their nature such as ``Copyright Cols``, ``Origin Cols``, ``License Cols`` diff --git a/docs/source/how-to-guides/load-your-data/import-json.rst b/docs/source/how-to-guides/load-your-data/import-json.rst index 7a49c2bb..ce4cc684 100644 --- a/docs/source/how-to-guides/load-your-data/import-json.rst +++ b/docs/source/how-to-guides/load-your-data/import-json.rst @@ -1,6 +1,6 @@ -============================================== +============================= :index:`Import a JSON File` -============================================== +============================= To import a ScanCode JSON file: diff --git a/docs/source/how-to-guides/lookup-scan-info/index.rst b/docs/source/how-to-guides/lookup-scan-info/index.rst index d978f677..307a2d59 100644 --- a/docs/source/how-to-guides/lookup-scan-info/index.rst +++ b/docs/source/how-to-guides/lookup-scan-info/index.rst @@ -1,6 +1,6 @@ -================================== +======================================== :index:`Look Up Your Scan information` -================================== +======================================== To view scan information: diff --git a/docs/license.rst b/docs/source/license.rst similarity index 100% rename from docs/license.rst rename to docs/source/license.rst diff --git a/docs/source/technical-reference/index.rst b/docs/source/technical-reference/index.rst index 0b1cf4a8..3217ccc1 100644 --- a/docs/source/technical-reference/index.rst +++ b/docs/source/technical-reference/index.rst @@ -13,98 +13,6 @@ Underlying Technology Platform Support ================ -ScanCode Workbench Supported Platforms --------------------------------------- - -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 | x64 | 2 | | -+-------------+------------------+----------+------------+-----------------------------------------+ -| Windows | Windows 10 | x64 | 1 | Verified to be able to run the prebuilt | -+-------------+------------------+----------+------------+-----------------------------------------+ -| Windows | Windows 11 | x64 | 1 | Verified to be able to run the prebuilt | -+-------------+------------------+----------+------------+-----------------------------------------+ -| MacOS | 10.15 Catalina | x64 | 2 | | -+-------------+------------------+----------+------------+-----------------------------------------+ -| MacOS | 11 Big Sur |x64, arm64| 2 | Verified to be able to run the prebuilt | -+-------------+------------------+----------+------------+-----------------------------------------+ -| MacOS | 12 Monterey |x64, arm64| 1 | Verified to be able to run the prebuilt | -+-------------+------------------+----------+------------+-----------------------------------------+ -| MacOS | 13 Ventura |x64, arm64| 1 | Verified to be able to run the prebuilt | -+-------------+------------------+----------+------------+-----------------------------------------+ -| Linux Deb | Ubuntu 12.04 | x64 | 2 | 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 | 1 | Verified to be able to run the prebuilt | -| | | | | binaries of Electron. | -+-------------+------------------+----------+------------+-----------------------------------------+ -| Linux Deb | Ubuntu 18.xx | x64 | 1 | Verified to be able to run the prebuilt | -| | | | | binaries of Electron. | -+-------------+------------------+----------+------------+-----------------------------------------+ -| Linux Deb | Ubuntu 20.xx | x64 | 1 | Verified to be able to run the prebuilt | -| | | | | binaries of Electron. | -+-------------+------------------+----------+------------+-----------------------------------------+ -| Linux Deb | Ubuntu 22.xx | x64 | 1 | 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 -^^^^^ - -Binaries for both x64 & arm64 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 +* Linux - ``x64`` +* Windows 10/11 - ``x64`` +* MacOS - ``x64``, ``arm64`` diff --git a/docs/source/ui-reference/chart-summary-view.rst b/docs/source/ui-reference/chart-summary-view.rst index c6dfdde1..8e90bb97 100644 --- a/docs/source/ui-reference/chart-summary-view.rst +++ b/docs/source/ui-reference/chart-summary-view.rst @@ -1,4 +1,4 @@ -.. _license-explorer: +.. _chart-summary-view: =========================== :index:`Chart Summary View` diff --git a/docs/source/ui-reference/copyright-info-dashboard.rst b/docs/source/ui-reference/copyright-info-dashboard.rst index 6bbeb85c..d4638d2e 100644 --- a/docs/source/ui-reference/copyright-info-dashboard.rst +++ b/docs/source/ui-reference/copyright-info-dashboard.rst @@ -1,6 +1,6 @@ -============================ +=================================== :index:`Copyright Info Dashboard` -============================ +=================================== Scan must have ``--license`` option for License Info Dashboard diff --git a/docs/source/ui-reference/dependency-info-dashboard.rst b/docs/source/ui-reference/dependency-info-dashboard.rst index f128fd7d..20492df1 100644 --- a/docs/source/ui-reference/dependency-info-dashboard.rst +++ b/docs/source/ui-reference/dependency-info-dashboard.rst @@ -1,6 +1,6 @@ -============================ +===================================== :index:`Dependency Info Dashboard` -============================ +===================================== Scan must have ``--package`` option for Dependency Info Dashboard diff --git a/docs/source/ui-reference/license-explorer.rst b/docs/source/ui-reference/license-explorer.rst index 7ba2c2da..4acde19b 100644 --- a/docs/source/ui-reference/license-explorer.rst +++ b/docs/source/ui-reference/license-explorer.rst @@ -7,7 +7,7 @@ Details of Top level License detections and clues License Navigation Pane -------------------------- +------------------------------- User can scroll through the licenses and select particular license to see detailed information in the License details pane. Licenses are divided into two sections: - License Detections - License Clues @@ -18,35 +18,36 @@ These sections' height & navigation pane's width can be adjusted as per convenie License Details Pane ----------------------- +------------------------------------------ User can see detailed information of the license selected in the navigation pane. Title of details pane - License Expression Instances - No. of times license is detected Score - Shown only for clues, indicating clue's confidence about the license Matches Table -User can view the match details resulting the selected license - - ``Score`` - - ``Matched length`` - - ``Match Coverage`` - - ``Matcher`` - - ``Matched Text`` - | User can click on the text to view a diff of Matched & Rule text - | (Requires ``--license-references`` flag) - - ``Rule`` - User can click on the Rule to open the rule used by scancode-toolkit in browser - - ``SPDX License expression`` +User can view the match details resulting the selected license + +- ``Score`` +- ``Matched length`` +- ``Match Coverage`` +- ``Matcher`` +- ``Matched Text`` + | User can click on the text to view a diff of Matched & Rule text + | (Requires ``--license-references`` flag) +- ``Rule`` - User can click on the Rule to open the rule used by scancode-toolkit in browser +- ``SPDX License expression`` File Regions Table User can view the files in which selected license was detected - - ``Path`` - Path of file, User can click on it to view the specific file in TableView - - ``Lines`` - Specific lines in the file at which license was detected - - ``Detection origin`` - Type of file +- ``Path`` - Path of file, User can click on it to view the specific file in TableView +- ``Lines`` - Specific lines in the file at which license was detected +- ``Detection origin`` - Type of file View License details, go to & from file <-> license explorer --------------------- +-------------------------------------------------------------------------------- .. image:: data/license-explorer/license-explorer-nav.gif View Matched Text diff ------------------------- +-------------------------------------------- .. image:: data/license-explorer/license-explorer-matchedtext.gif \ No newline at end of file diff --git a/docs/source/ui-reference/license-info-dashboard.rst b/docs/source/ui-reference/license-info-dashboard.rst index 61c63674..735ce40b 100644 --- a/docs/source/ui-reference/license-info-dashboard.rst +++ b/docs/source/ui-reference/license-info-dashboard.rst @@ -1,6 +1,6 @@ -============================ +================================ :index:`License Info Dashboard` -============================ +================================ Scan must have ``--license`` option for License Info Dashboard diff --git a/docs/source/ui-reference/package-explorer.rst b/docs/source/ui-reference/package-explorer.rst index b410678d..5b6355be 100644 --- a/docs/source/ui-reference/package-explorer.rst +++ b/docs/source/ui-reference/package-explorer.rst @@ -7,7 +7,7 @@ Details of Top level License detections and clues License Navigation Pane --------------------- +-------------------------------- User can scroll through the licenses and select particular license to see detailed information in the License details pane. Licenses are divided into two sections: - License Detections - License Clues @@ -26,18 +26,20 @@ Score - Shown only for clues, indicating clue's confidence about the license Matches Table User can view the match details resulting the selected license - - ``Score`` - - ``Matched length`` - - ``Match Coverage`` - - ``Matcher`` - - ``Matched Text`` - - ``Rule`` - User can click on the Rule to see the rule used by scancode-toolkit - - ``SPDX License expression`` + +- ``Score`` +- ``Matched length`` +- ``Match Coverage`` +- ``Matcher`` +- ``Matched Text`` +- ``Rule`` - User can click on the Rule to see the rule used by scancode-toolkit +- ``SPDX License expression`` File Regions Table User can view the files in which selected license was detected - - ``Path`` - Path of file, User can click on it to view the specific file in TableView - - ``Lines`` - Specific lines in the file at which license was detected - - ``Detection origin`` - Type of file + +- ``Path`` - Path of file, User can click on it to view the specific file in TableView +- ``Lines`` - Specific lines in the file at which license was detected +- ``Detection origin`` - Type of file .. image:: data/license-explorer/license-explorer-nav.gif \ No newline at end of file diff --git a/docs/source/ui-reference/package-info-dashboard.rst b/docs/source/ui-reference/package-info-dashboard.rst index 17e487ef..a84590fa 100644 --- a/docs/source/ui-reference/package-info-dashboard.rst +++ b/docs/source/ui-reference/package-info-dashboard.rst @@ -1,8 +1,8 @@ .. _package-info-dashboard: -============================ +=================================== :index:`Package Info Dashboard` -============================ +=================================== Scan must have ``--package`` option for License Info Dashboard diff --git a/docs/source/ui-reference/table-view.rst b/docs/source/ui-reference/table-view.rst index a6f2d7ac..32c5c1ab 100644 --- a/docs/source/ui-reference/table-view.rst +++ b/docs/source/ui-reference/table-view.rst @@ -19,80 +19,86 @@ Column groups ---------------- Copyright - - ``copyright_statements`` - - ``copyright_holders`` - - ``copyright_authors`` - - ``copyright_start_line`` - - ``copyright_end_line`` + +- ``copyright_statements`` +- ``copyright_holders`` +- ``copyright_authors`` +- ``copyright_start_line`` +- ``copyright_end_line`` File - - ``type`` - - ``name`` - - ``extension`` - - ``size`` - - ``programming_language`` - - ``mime_type`` - - ``file_type`` - - ``is_binary`` - - ``is_text`` - - ``is_archive`` - - ``is_media`` - - ``is_source`` - - ``is_script`` + +- ``type`` +- ``name`` +- ``extension`` +- ``size`` +- ``programming_language`` +- ``mime_type`` +- ``file_type`` +- ``is_binary`` +- ``is_text`` +- ``is_archive`` +- ``is_media`` +- ``is_source`` +- ``is_script`` License - - ``detected_license_expression`` - - ``detected_license_expression_spdx`` - - ``percentage_of_license_text`` - - ``license_detections`` - - ``license_policy`` - - ``license_clues`` + +- ``detected_license_expression`` +- ``detected_license_expression_spdx`` +- ``percentage_of_license_text`` +- ``license_detections`` +- ``license_policy`` +- ``license_clues`` Origin - - ``copyright_statements`` - - ``license_policy`` - - ``email`` - - ``url`` - - ``mime_type`` - - ``file_type`` - - ``programming_language`` + +- ``copyright_statements`` +- ``license_policy`` +- ``email`` +- ``url`` +- ``mime_type`` +- ``file_type`` +- ``programming_language`` Package - - ``package_data_type`` - - ``package_data_name`` - - ``package_data_version`` - - ``package_data_extracted_license_statement`` - - ``package_data_declared_license_expression`` - - ``package_data_declared_license_expression_spdx`` - - ``package_data_primary_language`` - - ``for_packages`` + +- ``package_data_type`` +- ``package_data_name`` +- ``package_data_version`` +- ``package_data_extracted_license_statement`` +- ``package_data_declared_license_expression`` +- ``package_data_declared_license_expression_spdx`` +- ``package_data_primary_language`` +- ``for_packages`` Misc - - ``scan_error`` + +- ``scan_error`` .. image:: data/tableview/tableview-intro.gif Preset Column Groups ------------------------- +------------------------------ The columns are grouped based on their nature such as ``Copyright Cols``, ``Origin Cols``, ``License Cols``, etc. User can select one of these groups using the corresponding buttons available in the quick actions row. .. image:: data/tableview/tableview-column-groups.gif View Custom set of columns ------------------------- +---------------------------------------- In addition to the preset groups, Users can select a custom set of columns by using the ``Custom Columns`` button found in the quick actions row. .. image:: data/tableview/tableview-custom-columns.gif Pin columns ------------------------- +------------------------------- Users can pin any column(s) to the left by dragging them through the column-header towards the left .. image:: data/tableview/tableview-pin-columns.gif Column wise filter & search ------------------------- +------------------------------------------- User can easily filter rows based on specific column values or use advanced search using ``and``, ``or`` in combination with different search patterns like ``Contains``, ``Starts with``, etc. .. image:: data/tableview/tableview-column-filter-search.gif