Improve the scan codebase cl tutorail (#239)

* Improve the scan codebase cl tutorail

      * Updating the text content to follow the docker cl tutorial
      * Updating the warning text in the user interface file
      * Adding minor updates to the scancodeio introduction file

Signed-off-by: Hanan Younes <[email protected]>

Author: hyounes4560

docs/introduction.rst

@@ -32,16 +32,16 @@ that are adapted to a software project's unique context and technology platform
 can be difficult. This will require deploying and running multiple specialized
 tools and merge their results with a consistent workflow. Moreover,
 when reusing thousands of open source packages is becoming commonplace,
-code scans pipelines need to be scripted as code and running on servers backed
+code scans pipelines need to be scripted as code is running on servers backed
 by a shared database, not on a laptop.
 
 For instance, when you analyze Docker container images, there could be hundreds
 to thousands of system packages, such as Debian, RPM, Alpine, and application
 packages, including npm, PyPI, Rubygems, Maven, installed in an image
-side-by-side with your own code. Taking care of all these can be
+side-by-side with your own code. Taking care of all this can be
 an extremely hard task, and that's when **ScanCode.io** comes into play to help
 organizing these complex code analysis as scripted pipelines and store their
-results in a uniform database for automated code analysis.
+results in a database for automated code analysis.
 
 
 What is ScanPipe?
@@ -73,9 +73,10 @@ are planning to start a new one, consider the following questions:
 2. **Complexity**: Does the project use many third-party components or technologies?
 3. **Reproducibility**: Is it important that the results are reproducible, traceable, and auditable?
 
-If you answered "yes" to any of the above, keep reading - ScanPipe can help you.
-If the answer is "no" to all of the above, which is a valid scenario, e.g., when you
-are doing small-scale analysis, ScanPipe may provide only limited benefit for you.
+If you answered **"yes"** to any of the above, keep reading - ScanPipe can help
+you. If the answer is **"no"** to all of the above, which is a valid scenario,
+e.g., when you are doing small-scale analysis, ScanPipe may provide only limited
+benefit for you.
 
 The first set of available pipelines helps automate the analysis of Docker
 container images and virtual machine (VM) disk images that often harbor

docs/tutorial-2.rst

@@ -2,36 +2,67 @@
 
 Scan Codebase (command line)
 ============================
+The focus of this tutorial is to guide you through scanning a codebase package
+using ScanCode.io.
+
+.. note::
+    This tutorial assumes you have a current version of ScanCode.io installed
+    locally on your machine. If you do not have it installed,
+    see our :ref:`installation` guide for instructions.
 
 Requirements
 ------------
+Before you follow the instructions in this tutorial, you need to:
 
-- **ScanCode.io is installed**, see :ref:`installation`
-- **Shell access** on the machine where ScanCode.io is installed
+- Install **ScanCode.io** locally
+- Download the following **package archive** and save it to your home directory: `asgiref-3.3.0-py3-none-any.whl <https://files.pythonhosted.org/packages/c0/e8/578887011652048c2d273bf98839a11020891917f3aa638a0bc9ac04d653/asgiref-3.3.0-py3-none-any.whl>`_
+- Have **Shell access** on the machine where ScanCode.io is installed
 
+Instructions
+------------
 
-Before you start
-----------------
+- Open a shell in the ScanCode.io installation directory and activate the
+  virtual environment - **virtualenv**:
 
-Download the following package archive save this in your home directory:
-`asgiref-3.3.0-py3-none-any.whl <https://files.pythonhosted.org/packages/c0/e8/578887011652048c2d273bf98839a11020891917f3aa638a0bc9ac04d653/asgiref-3.3.0-py3-none-any.whl>`_
+.. code-block:: console
 
+    $ source bin/activate
 
-Step-by-step
-------------
+.. code-block:: console
 
-- Open a shell in the ScanCode.io installation directory and activate the virtualenv::
+    >> (scancodeio) $
 
-    $ source bin/activate
+- Create a new project named ``asgiref``:
 
-- The following command will create a new project named ``asgiref``,
-  add the archive as an input for the project,
-  add the ``scan_codebase`` pipeline, and execute it::
+.. code-block:: console
 
-    $ scanpipe create-project asgiref \
-        --input-file ~/asgiref-3.3.0-py3-none-any.whl \
-        --pipeline scan_codebase \
-        --execute
+    $ scanpipe create-project asgiref
+
+.. code-block:: console
+
+    >> Project asgiref created with work directory projects/asgiref-072c89db
+
+- Add the package archive to the project workspace's :guilabel:`input/`
+  directory:
+
+.. code-block:: bash
+
+    $ scanpipe add-input --project asgiref --input-file ~/asgiref-3.3.0-py3-none-any.whl
+
+.. code-block:: console
+
+    >> File(s) copied to the project inputs directory:
+      - asgiref-3.3.0-py3-none-any.whl
+
+- Add the ``scan_codebase`` pipeline to your project:
+
+.. code-block:: console
+
+    $ scanpipe add-pipeline --project asgiref scan_codebase
+
+.. code-block:: console
+
+    >> Pipeline(s) added to the project
 
 .. note::
     The content of the :guilabel:`input/` directory will be copied in the
@@ -41,5 +72,36 @@ Step-by-step
     :guilabel:`codebase/` directory in which case the ``--input`` option can be
     omitted.
 
-- The scan results as JSON and CSV will be available in the project
-  :guilabel:`output/` directory.
+- Run the ``scan_codebase`` pipeline on your project. The pipeline execution
+  progress is shown within the following command's output:
+
+.. code-block:: bash
+
+    $ scanpipe execute --project asgiref
+
+.. code-block:: console
+
+    >> Pipeline scan_codebase run in progress..
+       2021-07-12 17:45:53.85 Pipeline [scan_codebase] starting
+       2021-07-12 17:45:53.85 Step [copy_inputs_to_codebase_directory] starting
+       2021-07-12 17:45:53.86 Step [copy_inputs_to_codebase_directory] completed in 0.00 seconds
+       2021-07-12 17:45:53.86 Step [run_extractcode] starting
+       [...]
+       2021-07-12 17:46:01.61 Pipeline completed
+
+- Finally, you can view your scan results in JSON or CSV file formats inside
+  the project's :guilabel:`output/` directory.
+
+.. tip::
+    The ``inputs`` and ``pipelines`` can be provided at the same time when
+    calling the ``create-project`` command. For instance, the following command
+    will create a new project named ``asgiref``, add the package archive as the
+    project input, add the ``scan_codebase`` pipeline to the project, and
+    execute it:
+
+.. code-block:: bash
+
+    $ scanpipe create-project asgiref \
+        --input-file ~/asgiref-3.3.0-py3-none-any.whl \
+        --pipeline scan_codebase \
+        --execute

docs/user-interface.rst

@@ -90,8 +90,8 @@ to your project by clicking the **"Add inputs"** and **"Add pipeline"** buttons.
 .. image:: images/UI-4-new.png
 
 .. warning::
-    You will not be able to add more inputs once a pipeline has been run on the project.
-    You can add and run more pipelines though.
+    You will not be able to add any extra inputs once a pipeline has been run on
+    the project. However, you still can add and run extra pipelines as needed!
 
 Within each project, you can view your project details, review the results of
 the pipeline execution, or download the output files.