Merge branch 'feature/doc-update' into 'develop'

feature/doc-update: add more details in README

See merge request !2

README.md

-Ansible Inventory Generator
-Overview
+# Ansible Inventory Generator
 
-This project aims to automate the generation of Ansible inventory files by pulling data from the WFO API.
+## Overview
 
-Features
+Tool for the automated generation of Ansible inventory files by pulling data extracted from the WFO API.
 
-    Generate Ansible inventory from WFO API.
-    Save processed data to appropriate inventory file(s).
-    Ensure no alteration to existing inventory files in case of process failure.
+## Features
 
-Once installed, you can use the `ansible_inventory_generator` command to generate the Ansible inventory from the API:
+* Generate Ansible inventory from WFO API.
+* Save processed data to appropriate inventory file(s).
+* Ensure no alteration to existing inventory files in case of process failure.
+
+## Installation
+
+Install from PIP.
 
 ```bash
 pip install \
     --pre \
     --extra-index-url https://artifactory.software.geant.org/artifactory/api/pypi/geant-swd-pypi/simple \
     ansible-inventory-generator
-    
+```
+
+## Deployment
+
+Fill in environment variables and run the command to generate the Ansible inventory from the API.
+
+```bash
+# Rewritting environment variables
+## URL of the WFO API (change IP only)
 export api_url=http://127.0.0.1:8080/api/v1/subscriptions/routers
+## Full paths where this tool will save variables and inventory files
 export host_vars_dir=/path/to/base/hostvars/dir
-export vars_file_name=wfo_vars.yaml
 export hosts_file_dir=/path/to/base/hosts/dir
-export gso_api_key=get_this_token_from_gso_admin_based_on_your_environment
+## Full path where this tool will save the WFO variables
+export vars_file_name=wfo_vars.yaml
+## Token provided by each GSO instance admin (varies per environment)
+export gso_api_key=<fill_with_gso_token>
 
+# Execution of the command to generate the Ansible inventory files
 ansible_inventory_generator
+```
+
+Ansible inventory files will be available under the path stated under `hosts_file_dir`.
+
+## Troubleshooting
+
+### Issues when installing the PIP package
+
+When experiencing an error like the following, switch to the user that has permissions over `/usr/local/bin`:
+```bash
+PermissionError: [Errno 13] Permission denied: '/usr/local/bin/ansible_inventory_generator'
+```
+
+If facing an error like the following, it may suggest a compatibility issue (maybe with the version of setuptools, wheels or pip):
+```bash
+AttributeError: install_layout. Did you mean: 'install_platlib'?
+```
+To try to address it, run the following:
+```bash
+pip install -U pip setuptools wheel 
+```
+
+### 403 error when running the `ansible_inventory_generator` command
+
+This tool cannot reach the WFO API because it is authenticated.
+Correct it by redeploying WFO by first running `export OAUTH2_ACTIVE=false` and then re-running WFO.
+Alternatively, change `export api_url` to an authenticated instance of GSO.
\ No newline at end of file