Add a general scancodeio ui section (#234)

hyounes4560 · tdruez · web-flow · commit 4d486ff42ea7 · 2021-07-15T18:12:08.000+04:00
* Add a general scancodeio ui section * Adding the text content * Adding images * Adding minor updates to the scancodeio output section Signed-off-by: Hanan Younes <hyounes4560@conestogac.on.ca> * Minor refinements to the documentation #234 Signed-off-by: Thomas Druez <tdruez@nexb.com> Co-authored-by: Thomas Druez <tdruez@nexb.com>
diff --git a/docs/images/UI-1.png b/docs/images/UI-1.png
diff --git a/docs/images/UI-2.png b/docs/images/UI-2.png
diff --git a/docs/images/UI-3.png b/docs/images/UI-3.png
diff --git a/docs/images/UI-4-new.png b/docs/images/UI-4-new.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -16,14 +16,15 @@ you’ll find information on:
 
     introduction
     installation
-    docker-image
+    run-docker
+    user-interface
 
 .. toctree::
     :maxdepth: 2
     :caption: Tutorial
 
-    scanpipe-tutorial-1
-    scanpipe-tutorial-2
+    tutorial-1
+    tutorial-2
 
 .. toctree::
     :maxdepth: 2
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -16,11 +16,11 @@ Supported Platforms
     #. **Debian-based** Linux distributions
     #. **MacOS** 10.14 and up
 
-In addition, ScanCode.io can also be run through **Docker**; this is the preferred
-approach **on Windows**. Refer to the :ref:`docker_image` chapter for details.
+In addition, ScanCode.io can also be run with **Docker**; this is the preferred
+approach **on Windows**. Refer to the :ref:`run_docker` chapter for details.
 
 .. warning::
-   ScanCode.io can **Only** be run on Windows through `Docker <https://www.docker.com/>`_ or
+   ScanCode.io can **only** be run on Windows through `Docker <https://www.docker.com/>`_ or
    `Virtual Machines <https://www.virtualbox.org/>`_.
    However, to avoid any installation issues, it is **Not recommended** to run ScanCode.io on
    Windows machines.
@@ -67,7 +67,6 @@ latest/getting-started/install.html#prerequisites>`_ for more details.
 
     make dev
 
-
  .. note::
     You can specify the Python version during the ``make dev`` step using the following command::
 
@@ -105,7 +104,6 @@ You can validate the ScanCode.io installation by running the tests suite::
 
     make test
 
-
 Web Application
 ---------------
 
@@ -116,9 +114,11 @@ local webserver and access the app with::
 
 Then open your web browser and visit: http://127.0.0.1:8001/ to access the web application.
 
+:ref:`user_interface`
+
 .. note::
    Congratulations, you are now ready to use ScanCode.io, and you can move onto the **Tutorials**
-   section starting with the :ref:`scanpipe_tutorial_1` tutorial.
+   section starting with the :ref:`tutorial_1` tutorial.
 
 Upgrading
 ---------
@@ -129,3 +129,4 @@ If you already have the ScanCode.io repo cloned, you can upgrade to the latest v
     git pull
     make dev
     make migrate
+
diff --git a/docs/run-docker.rst b/docs/run-docker.rst
@@ -1,7 +1,10 @@
-.. _docker_image:
+.. _run_docker:
 
-Docker image
-============
+Run with Docker
+===============
+
+Running ScanCode.io with Docker containers is the preferred setup and ensure that all
+the features are available and working properly.
 
 Get Docker
 ----------
@@ -23,7 +26,6 @@ create an environment file, and build the Docker image::
     make envfile
     docker-compose build
 
-
 .. note::
     The image will need to be re-build when the ScanCode.io app source code if
     modified or updated.
@@ -35,7 +37,6 @@ Run your image as a container::
 
     docker-compose up
 
-
 At this point, the ScanCode.io app should be running at port 80 on your Docker host.
 Go to http://localhost/ on a web browser to access the web UI.
 
@@ -54,7 +55,6 @@ interface, for example::
 
     docker-compose run web ./manage.py create-project project_name
 
-
 .. note::
     Refer to :ref:`scanpipe_command_line` for the full list of commands.
 
diff --git a/docs/scancodeio-settings.rst b/docs/scancodeio-settings.rst
@@ -1,6 +1,6 @@
 .. _scancodeio_settings:
 
-ScanCode.io Settings
+Application Settings
 ====================
 
 The ``.env`` file is created at the root of the ScanCode.io codebase during its
diff --git a/docs/scanpipe-api.rst b/docs/scanpipe-api.rst
@@ -1,7 +1,7 @@
 .. _scanpipe_api:
 
-ScanPipe REST API
-=================
+REST API
+========
 
 To get started locally with the API:
 
diff --git a/docs/scanpipe-command-line.rst b/docs/scanpipe-command-line.rst
@@ -1,7 +1,7 @@
 .. _scanpipe_command_line:
 
-ScanPipe Commands Help
-======================
+Management Commands
+===================
 
 The main entry point is the :guilabel:`scanpipe` command which is available
 directly when you are in the activated virtualenv or at this path:
diff --git a/docs/scanpipe-output.rst b/docs/scanpipe-output.rst
@@ -27,8 +27,8 @@ the output file format with the ``–-format`` option:
 
 Web UI
 ^^^^^^
-When using the ScanCode.io web application, you can download the results of a project
-in your prefer output format using the as buttons available from the project views:
+When using the ScanCode.io web application, you can download the results of your
+project in your preferred output format within the project page.
 
 .. image:: images/output-download-results.png
 
diff --git a/docs/tutorial-1.rst b/docs/tutorial-1.rst
@@ -1,4 +1,4 @@
-.. _scanpipe_tutorial_1:
+.. _tutorial_1:
 
 Docker Image Analysis (command line)
 ====================================
diff --git a/docs/tutorial-2.rst b/docs/tutorial-2.rst
@@ -1,4 +1,4 @@
-.. _scanpipe_tutorial_2:
+.. _tutorial_2:
 
 Scan Codebase (command line)
 ============================
diff --git a/docs/user-interface.rst b/docs/user-interface.rst
@@ -0,0 +1,101 @@
+.. _user_interface:
+
+User Interface
+==============
+
+As you may have noticed reading through the documentation, the focus is mainly
+on installing, running, and using ScanCode.io through the command line.
+However, this is not the only way to interact with ScanCode.io, especially when
+creating and managing projects. For some tasks, viewing a visual representation
+of given scan results is preferable to textual output files, especially for
+users who are more comfortable using a user interface.
+
+As mentioned in the installation guide, ScanCode.io offers a web application to
+create and manage your projects from a browser. You’ll get access to this
+visual interface when you successfully install ScanCode.io locally.
+
+You can start the local web server and access the app with::
+
+    make run
+
+To access the web application, open your web browser and visit: http://127.0.0.1:8001/
+
+.. note::
+    All the capabilities offered by the ScanCode.io Web Interface are also available as
+    :ref:`scanpipe_command_line` and in the :ref:`scanpipe_api`.
+
+Home Screen
+-----------
+
+When you open the web application for the first
+time, the home screen will appear. From this screen, you'll be able to
+create a new project, search your existing projects, view or download scan
+results, access documentation, and more.
+
+.. image:: images/UI-1.png
+
+Creating a New Project
+----------------------
+
+Creating a project is the first step that needs to be performed before you
+can start using ScanCode.io. There are two **"New Project"** buttons on the
+home screen, as shown in the previous screenshot. To create a new project,
+click on either button, and you will be directed to the **"Create a Project"**
+page.
+
+.. image:: images/UI-2.png
+
+As shown above, creating a project involves filling in the following input
+fields:
+
+Name
+^^^^
+
+To create a project, you must provide a unique name for the new project.
+
+Inputs
+^^^^^^
+
+You can upload files available on your machine or add links to desired input files,
+such as package archives or Docker images, as the input to your project.
+If you are providing more than one URL as the project input, make sure to add one URL
+per line.
+
+.. tip::
+    Docker images can be provided as inputs to be fetched using the
+    ``docker://docker-reference`` syntax in the **"Download URLs"** field.
+    For example: ``docker://postgres:13``
+
+Pipeline
+^^^^^^^^
+
+Use the drop-down list to select one of the available pipelines depending on
+your use-case. When you add a pipeline, you can check the
+**"Execute pipeline now"** checkbox, which will add and execute the selected
+pipeline in one operation.
+
+.. note::
+    If you're not sure of which pipeline to select, refer to the
+    pipelines details on the right pane of the **"Create a Project"** page,
+    as shown above.
+
+You can still create a new project while leaving the **Inputs** and **Pipeline**
+fields blank; however, it's mandatory to provide a project **Name**!
+
+.. image:: images/UI-3.png
+
+Once successfully created, you can later add any needed inputs and pipelines
+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.
+
+Within each project, you can view your project details, review the results of
+the pipeline execution, or download the output files.
+
+.. note::
+    Please refer to the :ref:`scanpipe_output` page for more details about your
+    scan results.
