diff --git a/README.rst b/README.rst index 413567056e9..30dca944955 100644 --- a/README.rst +++ b/README.rst @@ -119,10 +119,10 @@ Other Important Documentation Pages: - A `synopsis `_ of ScanCode command line options. -- Tutorials on: +- How-Tos on: - - `How to run a scan `_ - - `How to visualize scan results `_ + - `Run a scan `_ + - `Visualize scan results `_ - An exhaustive list of `all available options `_ @@ -171,7 +171,7 @@ After ScanCode is installed successfully you can run an example scan printed on scancode -clip --json-pp - samples -Follow the `How to Run a Scan `_ +Follow the `How to Run a Scan `_ tutorial to perform a basic scan on the ``samples`` directory distributed by default with ScanCode. @@ -180,8 +180,8 @@ See more command examples:: scancode --examples See `How to select what will be detected in a scan -`_ -and `How to specify the output format `_ +`_ +and `How to specify the output format `_ for more information. You can also refer to the `command line options synopsis @@ -203,7 +203,7 @@ directory:: ./extractcode mytar.tar.bz2 See `all extractcode options `_ -and `how to extract archives `_ for details. +and `how to extract archives `_ for details. Support diff --git a/docs/source/cli-reference/simple-examples.rst b/docs/source/cli-reference/simple-examples.rst index 306a4041a6d..971a41f7bd4 100644 --- a/docs/source/cli-reference/simple-examples.rst +++ b/docs/source/cli-reference/simple-examples.rst @@ -1,3 +1,3 @@ .. _how_to_run_a_scan: -.. include:: /tutorials/how_to_run_a_scan.rst +.. include:: /how-to-guides/how_to_run_a_scan.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index cf0529c0a33..58d09d42a5a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -18,7 +18,9 @@ # -- Project information ----------------------------------------------------- project = "ScanCode-Toolkit" -copyright = "nexB Inc. and others." +copyright = "nexB Inc. and others." + \ + "Except where otherwise noted, this documentation is " + \ + "licensed under a cc-by-4.0" author = "AboutCode.org authors and contributors" # -- General configuration --------------------------------------------------- diff --git a/docs/source/getting-started/home.rst b/docs/source/getting-started/home.rst index 5e496d5d65e..03eea9a4453 100644 --- a/docs/source/getting-started/home.rst +++ b/docs/source/getting-started/home.rst @@ -135,4 +135,12 @@ audit function as they like on their own. Thank you for giving ScanCode a try! + +License +------- +ScanCode is licensed under Apache-2.0 and others. Datasets contributed is +subject to CC-BY-4.0. See `License +`_ +for details. + .. include:: /rst_snippets/other_imp_doc.rst diff --git a/docs/source/getting-started/install.rst b/docs/source/getting-started/install.rst index 95e64cfa2c7..7162ca2c6a2 100644 --- a/docs/source/getting-started/install.rst +++ b/docs/source/getting-started/install.rst @@ -423,6 +423,10 @@ For more information on Python virtualenv, visit this no default dependencies on pre-built binaries. This may come handy for some special use cases such as packaging for a Linux or FreeBSD distro. +.. NOTE:: + + Refer :ref:`run_as_library` for usage samples. + To uninstall, run:: diff --git a/docs/source/getting-started/newcomer.rst b/docs/source/getting-started/newcomer.rst index b62d242bae4..438f604d26c 100644 --- a/docs/source/getting-started/newcomer.rst +++ b/docs/source/getting-started/newcomer.rst @@ -115,19 +115,19 @@ Use ScanCode Better All Tutorials/How-Tos ^^^^^^^^^^^^^^^^^^^^^ -The Tutorials are: +The How-To's are: #. :ref:`how_to_run_a_scan` #. :ref:`how_to_visualize_scan_results` -#. :ref:`how_to_set_what_scan_detects` #. :ref:`how_to_extract_archives` #. :ref:`how_to_specify_output_format` -#. :ref:`how_to_add_post_scan_plugin` - -The How-To's are: - +#. :ref:`how_to_set_what_scan_detects` #. :ref:`add_new_license_for_det` #. :ref:`add_new_license_det_rule` +#. :ref:`install_new_license_plugin` +#. :ref:`generate_attribution` +#. :ref:`how_to_add_post_scan_plugin` + .. _newcomer_whats_new: diff --git a/docs/source/how-to-guides/add_new_license.rst b/docs/source/how-to-guides/add_new_license.rst index 85b3a8bdd28..7a77f7ab845 100644 --- a/docs/source/how-to-guides/add_new_license.rst +++ b/docs/source/how-to-guides/add_new_license.rst @@ -1,7 +1,7 @@ .. _add_new_license_for_det: -How To Add a New License for Detection -====================================== +Add a New License for Detection +=============================== How to add a new license for detection? --------------------------------------- diff --git a/docs/source/how-to-guides/add_new_license_detection_rule.rst b/docs/source/how-to-guides/add_new_license_detection_rule.rst index 19c8b680fd4..e62856266fa 100644 --- a/docs/source/how-to-guides/add_new_license_detection_rule.rst +++ b/docs/source/how-to-guides/add_new_license_detection_rule.rst @@ -1,7 +1,7 @@ .. _add_new_license_det_rule: -How to Add New License Rules for Enhanced Detection -=================================================== +Add New License Rules for Enhanced Detection +============================================ ScanCode relies on license rules to detect licenses. A rule is a simple text file containing a license text or notice or mention with YAML frontmatter with data diff --git a/docs/source/tutorials/data/components_sample.gif b/docs/source/how-to-guides/data/components_sample.gif similarity index 100% rename from docs/source/tutorials/data/components_sample.gif rename to docs/source/how-to-guides/data/components_sample.gif diff --git a/docs/source/tutorials/data/files_sample.png b/docs/source/how-to-guides/data/files_sample.png similarity index 100% rename from docs/source/tutorials/data/files_sample.png rename to docs/source/how-to-guides/data/files_sample.png diff --git a/docs/source/tutorials/data/filter_sample.gif b/docs/source/how-to-guides/data/filter_sample.gif similarity index 100% rename from docs/source/tutorials/data/filter_sample.gif rename to docs/source/how-to-guides/data/filter_sample.gif diff --git a/docs/source/tutorials/data/scancode-toolkit-dynamic-html.png b/docs/source/how-to-guides/data/scancode-toolkit-dynamic-html.png similarity index 100% rename from docs/source/tutorials/data/scancode-toolkit-dynamic-html.png rename to docs/source/how-to-guides/data/scancode-toolkit-dynamic-html.png diff --git a/docs/source/tutorials/data/scancode-toolkit-extract.png b/docs/source/how-to-guides/data/scancode-toolkit-extract.png similarity index 100% rename from docs/source/tutorials/data/scancode-toolkit-extract.png rename to docs/source/how-to-guides/data/scancode-toolkit-extract.png diff --git a/docs/source/tutorials/data/scancode-toolkit-file-tree.png b/docs/source/how-to-guides/data/scancode-toolkit-file-tree.png similarity index 100% rename from docs/source/tutorials/data/scancode-toolkit-file-tree.png rename to docs/source/how-to-guides/data/scancode-toolkit-file-tree.png diff --git a/docs/source/tutorials/data/scancode-toolkit-filter-chart.png b/docs/source/how-to-guides/data/scancode-toolkit-filter-chart.png similarity index 100% rename from docs/source/tutorials/data/scancode-toolkit-filter-chart.png rename to docs/source/how-to-guides/data/scancode-toolkit-filter-chart.png diff --git a/docs/source/tutorials/data/scancode-toolkit-filter-zlib.png b/docs/source/how-to-guides/data/scancode-toolkit-filter-zlib.png similarity index 100% rename from docs/source/tutorials/data/scancode-toolkit-filter-zlib.png rename to docs/source/how-to-guides/data/scancode-toolkit-filter-zlib.png diff --git a/docs/source/tutorials/data/views_sample.gif b/docs/source/how-to-guides/data/views_sample.gif similarity index 100% rename from docs/source/tutorials/data/views_sample.gif rename to docs/source/how-to-guides/data/views_sample.gif diff --git a/docs/source/tutorials/data/workbench_dashboard.png b/docs/source/how-to-guides/data/workbench_dashboard.png similarity index 100% rename from docs/source/tutorials/data/workbench_dashboard.png rename to docs/source/how-to-guides/data/workbench_dashboard.png diff --git a/docs/source/tutorials/data/workbench_launch.png b/docs/source/how-to-guides/data/workbench_launch.png similarity index 100% rename from docs/source/tutorials/data/workbench_launch.png rename to docs/source/how-to-guides/data/workbench_launch.png diff --git a/docs/source/how-to-guides/generate_attribution.rst b/docs/source/how-to-guides/generate_attribution.rst index 9deeb84f746..fb653488b3d 100644 --- a/docs/source/how-to-guides/generate_attribution.rst +++ b/docs/source/how-to-guides/generate_attribution.rst @@ -1,7 +1,7 @@ .. _generate_attribution: -How To Generate Attribution from a ScanCode Scan -================================================ +Generate Attribution from a ScanCode Scan +========================================= How To generate attribution from a ScanCode scan? ------------------------------------------------- diff --git a/docs/source/tutorials/how_to_add_a_post_scan_plugin.rst b/docs/source/how-to-guides/how_to_add_a_post_scan_plugin.rst similarity index 100% rename from docs/source/tutorials/how_to_add_a_post_scan_plugin.rst rename to docs/source/how-to-guides/how_to_add_a_post_scan_plugin.rst diff --git a/docs/source/tutorials/how_to_extract_archives.rst b/docs/source/how-to-guides/how_to_extract_archives.rst similarity index 91% rename from docs/source/tutorials/how_to_extract_archives.rst rename to docs/source/how-to-guides/how_to_extract_archives.rst index 2cf1a2f3b60..5e3c1f9f91e 100644 --- a/docs/source/tutorials/how_to_extract_archives.rst +++ b/docs/source/how-to-guides/how_to_extract_archives.rst @@ -1,7 +1,7 @@ .. _how_to_extract_archives: -How To Extract Archives -======================= +Extract Archives +================ ScanCode-Toolkit provides archive extraction. This command can be used before running a scan over a codebase in order to ensure all archives are extracted. Archives found inside an extracted diff --git a/docs/source/tutorials/how_to_format_scan_output.rst b/docs/source/how-to-guides/how_to_format_scan_output.rst similarity index 94% rename from docs/source/tutorials/how_to_format_scan_output.rst rename to docs/source/how-to-guides/how_to_format_scan_output.rst index 89d238ef281..d0c3f082f20 100644 --- a/docs/source/tutorials/how_to_format_scan_output.rst +++ b/docs/source/how-to-guides/how_to_format_scan_output.rst @@ -1,7 +1,7 @@ .. _how_to_specify_output_format: -How to specify ScanCode Output Format -===================================== +Specify ScanCode Output Format +============================== A basic overview of formatting ScanCode Output is presented here. diff --git a/docs/source/tutorials/how_to_run_a_scan.rst b/docs/source/how-to-guides/how_to_run_a_scan.rst similarity index 97% rename from docs/source/tutorials/how_to_run_a_scan.rst rename to docs/source/how-to-guides/how_to_run_a_scan.rst index 5895f153c09..66ea88d652f 100644 --- a/docs/source/tutorials/how_to_run_a_scan.rst +++ b/docs/source/how-to-guides/how_to_run_a_scan.rst @@ -1,5 +1,5 @@ -How to Run a Scan -================= +Run a Scan +========== In this simple tutorial example, we perform a basic scan on the ``samples`` directory distributed by default with ScanCode. @@ -17,7 +17,7 @@ Looking into Files As mentioned previously, we are going to perform the scan on the ``samples`` directory distributed by default with ScanCode-Toolkit. Here's the directory structure and respective files: -.. image:: /tutorials/data/files_sample.png +.. image:: /how-to-guides/data/files_sample.png We notice here that the sample files contain a package ``zlib.tar.gz``. So we have to extract the archive before running the scan, to also scan the files inside this package. diff --git a/docs/source/tutorials/how_to_set_what_will_be_detected_in_a_scan.rst b/docs/source/how-to-guides/how_to_set_what_will_be_detected_in_a_scan.rst similarity index 95% rename from docs/source/tutorials/how_to_set_what_will_be_detected_in_a_scan.rst rename to docs/source/how-to-guides/how_to_set_what_will_be_detected_in_a_scan.rst index 4c572f04e37..ed400d23bf5 100644 --- a/docs/source/tutorials/how_to_set_what_will_be_detected_in_a_scan.rst +++ b/docs/source/how-to-guides/how_to_set_what_will_be_detected_in_a_scan.rst @@ -1,7 +1,7 @@ .. _how_to_set_what_scan_detects: -How to set what will be detected in Scan -======================================== +Set what will be detected in Scan +================================= ScanCode allows you to scan a codebase for license, copyright and other interesting information that can be discovered in files. The following options are available for detection when using diff --git a/docs/source/tutorials/how_to_visualize_scan_results.rst b/docs/source/how-to-guides/how_to_visualize_scan_results.rst similarity index 94% rename from docs/source/tutorials/how_to_visualize_scan_results.rst rename to docs/source/how-to-guides/how_to_visualize_scan_results.rst index 97cf774e371..43be03f9879 100644 --- a/docs/source/tutorials/how_to_visualize_scan_results.rst +++ b/docs/source/how-to-guides/how_to_visualize_scan_results.rst @@ -1,7 +1,7 @@ .. _how_to_visualize_scan_results: -How to Visualize Scan results -============================= +Visualize Scan results +====================== 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 diff --git a/docs/source/how-to-guides/index.rst b/docs/source/how-to-guides/index.rst index 113be1e1e46..559d005cdc3 100644 --- a/docs/source/how-to-guides/index.rst +++ b/docs/source/how-to-guides/index.rst @@ -6,7 +6,14 @@ .. toctree:: :maxdepth: 2 + how_to_run_a_scan + how_to_visualize_scan_results + how_to_extract_archives + how_to_format_scan_output + how_to_set_what_will_be_detected_in_a_scan add_new_license add_new_license_detection_rule install_new_license_plugin + run_as_library generate_attribution + how_to_add_a_post_scan_plugin diff --git a/docs/source/how-to-guides/install_new_license_plugin.rst b/docs/source/how-to-guides/install_new_license_plugin.rst index 1fc72017711..6e7142e6826 100644 --- a/docs/source/how-to-guides/install_new_license_plugin.rst +++ b/docs/source/how-to-guides/install_new_license_plugin.rst @@ -1,7 +1,7 @@ .. _install_external_licenses: -How to Install External Licenses to Use in License Detection -============================================================ +Install External Licenses to Use in License Detection +===================================================== Users can install external licenses and rules in the form of: diff --git a/docs/source/how-to-guides/run_as_library.rst b/docs/source/how-to-guides/run_as_library.rst new file mode 100644 index 00000000000..0096c313e19 --- /dev/null +++ b/docs/source/how-to-guides/run_as_library.rst @@ -0,0 +1,39 @@ +.. _run_as_library: + +Run as Library +============== + +If you’ve installed ScanCode-Toolkit as a library (:ref:`pip_install`), you +can directly import it into your Python scripts. + +ScanCode-Toolkit offers a wide range of callable functions. Each function +includes in-code documentation. Users can refer to it to understand the +purpose of each function, then import and use the ones they need. + +While listing them all isn't feasible, here are a few sample use cases. + +To Run a Scan +------------- + +:: + + from scancode.cli import run_scan + + +See https://github.com/aboutcode-org/scancode-toolkit/blob/develop/src/scancode/cli.py#L535 + + +Get YAML Safe Text +------------------ + +:: + + from licensedcode.models import get_yaml_safe_text + + +See https://github.com/aboutcode-org/scancode-toolkit/blob/develop/src/licensedcode/models.py#L777 + + +.. NOTE:: + + For more sample usages, refer https://github.com/nexB/scancode.io/blob/main/scanpipe/pipes/scancode.py diff --git a/docs/source/index.rst b/docs/source/index.rst index 0527a2c2ee1..32fe3990c5a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -43,18 +43,6 @@ Reference documents describe the Command Line options, and application concepts ---- -Tutorials ---------- - -Tutorial documents provide specific instructions to help you get started. - -.. toctree:: - :maxdepth: 2 - - tutorials/index - ----- - How-To Documents ---------------- diff --git a/docs/source/rst_snippets/other_imp_doc.rst b/docs/source/rst_snippets/other_imp_doc.rst index abb712cecb7..c4fe6a596a5 100644 --- a/docs/source/rst_snippets/other_imp_doc.rst +++ b/docs/source/rst_snippets/other_imp_doc.rst @@ -3,7 +3,6 @@ Other Important Documentation #. :ref:`scancode_cli_options` #. :ref:`how_to_run_a_scan` -#. :ref:`tutorials` #. :ref:`how_to_guides` #. :ref:`how_it_works` #. :ref:`contrib_code_dev` diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst deleted file mode 100644 index 4751d213620..00000000000 --- a/docs/source/tutorials/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _tutorials: - -**Basic Tutorials** -=================== - -.. toctree:: - :maxdepth: 2 - - how_to_run_a_scan - how_to_visualize_scan_results - how_to_extract_archives - how_to_format_scan_output - how_to_set_what_will_be_detected_in_a_scan - how_to_add_a_post_scan_plugin