Add new "Which pipeline should I use?" FAQ section #824

Signed-off-by: Thomas Druez <[email protected]>

docs/application-settings.rst

@@ -272,12 +272,30 @@ default the ``UTC`` time zone is used::
  You can view a detailed list of time zones `here.
  <https://en.wikipedia.org/wiki/List_of_tz_database_time_zones>`_
 
+.. _scancodeio_settings_purldb:
+
+PURLDB
+------
+
+Provide the URL and API key of your `PurlDB <https:/nexB/purldb/>`_
+instance.
+
+ ::
+
+ PURLDB_URL=https://your-purldb-domain/
+ PURLDB_API_KEY=apikeyexample
+
+.. _scancodeio_settings_vulnerablecode:
+
 VULNERABLECODE
 --------------
 
-You can either run your own instance of VulnerableCode or connect to the public one.
+You can either run your own instance of
+`VulnerableCode <https:/nexB/vulnerablecode/>`_
+or connect to the public one.
+
 Authentication is provided using an API key that you can obtain by registering at
 https://public.vulnerablecode.io/account/request_api_key/ ::
 
  VULNERABLECODE_URL=https://public.vulnerablecode.io/
- VULNERABLECODE_API_KEY=c1fa7dc1fd0a408880ba2dfdf63c1124abca9477
+ VULNERABLECODE_API_KEY=apikeyexample

docs/built-in-pipelines.rst

@@ -3,9 +3,12 @@
 Built-in Pipelines
 ==================
 
-As you may already know that pipelines are Python scripts that perform code
-analysis by executing a sequence of steps. ScanCode.io offers the following
-built-in—available—pipelines:
+Pipelines in ScanCode.io are Python scripts that facilitate code analysis by
+executing a sequence of steps. The platform provides the following built-in pipelines:
+
+.. tip::
+ If you are unsure which pipeline suits your requirements best, check out the
+ :ref:`faq_which_pipeline` section for guidance.
 
 .. _pipeline_base_class:
 
@@ -15,7 +18,7 @@ Pipeline Base Class
  :members:
  :member-order: bysource
 
-.. _pipeline_d2d:
+.. _pipeline_deploy_to_develop:
 
 Deploy To Develop
 -----------------

docs/faq.rst

@@ -12,33 +12,66 @@ How can I run a scan?
 You simply start by creating a :ref:`new project <user_interface_create_new_project>`
 and run the appropriate pipeline.
 
-ScanCode.io offers several :ref:`built_in_pipelines` depending on your input:
-
-- Docker image
-- Codebase drop
-- Package archive
-- Root filesystem
-- ScanCode-toolkit results
-- Manifest files
-- Deploy and develop codebase drops
+ScanCode.io offers several :ref:`built_in_pipelines` depending on your input, see above.
+
+.. _faq_which_pipeline:
+
+Which pipeline should I use?
+----------------------------
+
+Selecting the right pipeline for your needs depends primarily on the type of input
+data you have available.
+Here are some general guidelines based on different input scenarios:
+
+- If you have a **Docker image** as input, use the :ref:`docker <pipeline_docker>`
+ pipeline.
+- For a full **codebase compressed as an archive**, choose the
+ :ref:`scan_codebase <pipeline_scan_codebase>` pipeline.
+- If you have a **single package archive**, opt for the
+ :ref:`scan_package <pipeline_scan_package>` pipeline.
+- When dealing with a **Linux root filesystem** (rootfs), the
+ :ref:`root_filesystems <pipeline_root_filesystems>` pipeline is the appropriate
+ choice.
+- For processing the results of a **ScanCode-toolkit scan** or **ScanCode.io scan**,
+ use the :ref:`load_inventory <pipeline_load_inventory>` pipeline.
+- When you have **manifest files**, such as a
+ **CycloneDX BOM, SPDX document, lockfile**, etc.,
+ use the :ref:`inspect_manifest <pipeline_inspect_manifest>` pipeline.
+- For scenarios involving both a **development and deployment codebase**, consider using
+ the :ref:`deploy_to_develop <pipeline_deploy_to_develop>` pipeline.
+
+These pipelines will automatically execute the necessary steps to scan and create the
+packages, dependencies, and resources for your project based on the input data provided.
+
+After running one of the above pipelines, you may further **enhance your project data**
+by running some of the following additional pipelines:
+
+- If you wish to **find vulnerabilities** for packages and dependencies, you can use the
+ :ref:`find_vulnerabilities <pipeline_find_vulnerabilities>` pipeline.
+ Note that setting up :ref:`VulnerableCode <scancodeio_settings_vulnerablecode>` is
+ required for this pipeline to function properly.
+
+- To **populate the PurlDB** with your project discovered packages, use the
+ :ref:`populate_purldb <pipeline_populate_purldb>` pipeline.
+ Please ensure that you have set up
+ :ref:`PurlDB <scancodeio_settings_purldb>` before running this pipeline.
 
 What is the difference between scan_codebase and scan_package pipelines?
 ------------------------------------------------------------------------
 
-The key differences are that the ``scan_package`` pipeline treats the input
-as if it were a single package, such as a package archive, and computes a
-**License clarity** and a **Scan summary** to aggregate the package scan data:
+The key differences are that the :ref:`scan_package <pipeline_scan_package>` pipeline
+treats the input as if it were a single package, such as a package archive, and
+computes a **License clarity** and a **Scan summary** to aggregate the package scan
+data:
 
 .. image:: images/license-clarity-scan-summary.png
 
-In contrast, the ``scan_codebase`` pipeline is more of a general purpose pipeline and
-make no such single package assumption. It does not not compute such summary.
+In contrast, the :ref:`scan_codebase <pipeline_scan_codebase>` pipeline is more of a
+general purpose pipeline and make no such single package assumption.
+It does not not compute such summary.
 
 You can also have a look at the different steps for each pipeline from the
-:ref:`built_in_pipelines` documentation:
-
- - :ref:`pipeline_scan_package`
- - :ref:`pipeline_scan_codebase`
+:ref:`built_in_pipelines` documentation.
 
 Can I pause/resume a running pipeline?
 --------------------------------------
@@ -73,12 +106,12 @@ The pipeline documentation is available at :ref:`pipeline_docker` and its source
 at `docker.py <https:/nexB/scancode.io/blob/main/scanpipe/pipelines/docker.py>`_.
 It is hopefully designed to be simple and readable code.
 
-I am unable to run ScanCode.io on Windows?
-------------------------------------------
+I am able to run ScanCode.io on Windows?
+----------------------------------------
 
-Unfortunately, we never tested nor support Windows. Please refer to our
-:ref:`installation` section for more details on how to install ScanCode.io
-locally.
+Yes, you can use the :ref:run_with_docker installation. However, please be sure to
+carefully read the warnings, as running on Windows may have certain limitations or
+challenges.
 
 Is it possible to compare scan results?
 ---------------------------------------