Improve documentation and file headers consistency

This commit improves the documentation for the API, README, and the
docstrings.
The python files headers are also standardized.
Some typos are also fixed.

Signed-off-by: Kairo de Araujo <[email protected]>

Author: Kairo de Araujo

README.md

@@ -9,15 +9,12 @@ This project still not functional. Please wait for the first functional release
 
 The Tern REST API is a RESTful API for Tern Project.
 
-At the moment the API is not functional as it is still in the Specification
-development and project structure phase.
+Currently, the API is not functional as it is still in the Specification development and project structure phase.
 
-The specification is available at
-[Tern REST API Offline Swagger](https://tern-tools.github.io/tern-rest-api/) and
-contributions are welcome.
+The specification is available at [Tern REST API Offline Swagger](https://tern-tools.github.io/tern-rest-api/), and contributions are welcome.
 
-Mostly of the API is implemented in asynchronous way on the server side as the
-tern reports can take a while to be generated.
+Mainly the API is implemented asynchronously on the server-side as the tern
+reports can take a while to be generated.
 
 ```mermaid
   sequenceDiagram
@@ -26,36 +23,79 @@ tern reports can take a while to be generated.
     participant Tern
     User->>API: GET /api/v1/version
     API-->>User: 200 OK, JSON with version data
-    User->>API: GET /api/v1/reports
+    User->>API: POST /api/v1/reports with JSON payload
     API-->>User: 200 OK, JSON with request id
-    User->>API: GET /api/v1/reports/status
+    User->>API: POST /api/v1/reports/status with JSON payload
     API-->>User: 200 OK, JSON with status RUNNING
-    API->>Tern: Process the request caling asynchronous
+    API->>Tern: Process the request calling asynchronous
     Tern->>Tern: Processing
     loop
-    User->>API: GET /api/v1/reports/status
+    User->>API: POST /api/v1/reports/status with JSON payload
     Tern->>Tern: Processing
     API-->>User: 200 OK, JSON with status RUNNING or UNKOWN
     end
     Tern->>API: Provides the answer for the id
-    User->>API: GET /api/v1/reports/status
+    User->>API: POST /api/v1/reports/status with JSON payload
     API-->>User: 200 OK, JSON with status FAILED with error or DONE with report
 ```
 
 ## Development
 
-This repository has the ``requirements.txt`` and the ``requirements-dev.txt`` files to help building your virtual environment. I also recomend use pipenv to manage your virtual environment.
+This repository has the ``requirements.txt`` and the ``requirements-dev.txt``
+files to help build your virtual environment.
+
+We also recommend using [Pipenv](https://pipenv.pypa.io/en/latest/) to manage your virtual environment.
+
+```shell
+$ Pip install pipenv
+$ pipenv shell
+```
+
+Install development requirements
+```shell
+$ pipenv install -d
+```
+
+### Running the development Tern REST API
+
+
+Runing the API locally
+
+```shell
+$ flask run --reload
+```
+
+Open http://localhost:5000/ in your browser.
+
+## Tests
+
+We use [Tox](https://tox.wiki/en/latest/) to manage running the tests.
+
+Running tests
+```shell
+$ tox
+```
+
+## Managing the requirements
+
+Installing new requirements
 
 ```shell
-pip install pipenv
-pipenv shell
-pipenv install -d
+$ pipenv install {package}
 ```
 
-Runing the API locally:
+Development requirements
+```shell
+$ pipenv install -d {package}
+```
 
+Updating packages
 ```shell
-flask run --reload
+$ pipenv update
 ```
 
-Open http://localhost:5000/ in your browser.
+Updating the ``requirements.txt`` and ``requirements-dev.txt``
+```shell
+$ pipenv lock -r > requirements.txt
+$ pipenv lock -r -d > requirements-dev.txt
+```

app.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
 # Copyright (c) 2022 VMware, Inc. All Rights Reserved.

docs/swagger.json

@@ -12,7 +12,8 @@
                         }
                     }
                 },
-                "summary": "Tern report",
+                "summary": "Tern BoM report",
+                "description": "**Note**: This request will be processed assynchronous.",
                 "operationId": "post_report",
                 "parameters": [
                     {
@@ -39,7 +40,7 @@
                         }
                     }
                 },
-                "summary": "Tern report status/result",
+                "summary": "Request Tern BoM report status/result",
                 "operationId": "post_report_status",
                 "parameters": [
                     {
@@ -72,7 +73,7 @@
                         }
                     }
                 },
-                "summary": "Tern repoort",
+                "summary": "Get Tern Rest API base versions",
                 "operationId": "get_version",
                 "tags": [
                     "/version"
@@ -98,7 +99,7 @@
         },
         {
             "name": "/reports",
-            "description": "Tern Report"
+            "description": "Tern Bill of Materials Report"
         }
     ],
     "definitions": {

setup.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
 # Copyright (c) 2022 VMware, Inc. All Rights Reserved.

tern_api/__version__.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
 # Copyright (c) 2022 VMware, Inc. All Rights Reserved.

tern_api/api/__init__.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
 # Copyright (c) 2022 VMware, Inc. All Rights Reserved.

tern_api/api/v1/__init__.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
 # Copyright (c) 2022 VMware, Inc. All Rights Reserved.

tern_api/api/v1/common_models.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
 # Copyright (c) 2022 VMware, Inc. All Rights Reserved.

tern_api/api/v1/reports.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
 # Copyright (c) 2022 VMware, Inc. All Rights Reserved.
@@ -10,7 +11,7 @@
     report_model,
 )
 
-ns = Namespace("/reports", description="Tern Report")
+ns = Namespace("/reports", description="Tern Bill of Materials Report")
 
 
 @ns.route("")
@@ -47,7 +48,10 @@ class Report(Resource):
     @ns.response(200, "OK", report_response_request)
     @ns.expect(report_parameters)
     def post(self):
-        """Tern report"""
+        """Tern BoM report
+
+        **Note**: This request will be processed assynchronous.
+        """
 
 
 @ns.route("/status")
@@ -85,4 +89,4 @@ class ReportStatus(Resource):
     @ns.response(200, "OK", report_status_response)
     @ns.expect(report_status_parameters)
     def post(self):
-        """Tern report status/result"""
+        """Request Tern BoM report status/result"""

tern_api/api/v1/version.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 #
 # Copyright (c) 2022 VMware, Inc. All Rights Reserved.
@@ -40,7 +41,7 @@ class Version(Resource):
     @ns.response(400, "Bad request")
     @ns.response(500, "Internal Server Error")
     def get(self):
-        """Tern repoort"""
+        """Get Tern Rest API base versions"""
 
         response = get_version()
         return response.to_response()