Merge pull request #6 from NewTec-GmbH/doc/improvements

Improved documentation

README.md

@@ -2,17 +2,24 @@
 
 CLI tool for easy usage of the Superset API.
 
-[![License](https://img.shields.io/badge/license-bsd-3.svg)](https://choosealicense.com/licenses/bsd-3-clause/) [![Repo Status](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) [![CI](https://github.com/NewTec-GmbH/pySupersetCli/actions/workflows/ci.yml/badge.svg)](https://github.com/NewTec-GmbH/pySupersetCli/actions/workflows/ci.yml)
-
-* [Installation](#installation)
-* [Overview](#overview)
-* [Usage](#usage)
-* [Commands](#commands)
-* [Examples](#examples)
-* [Used Libraries](#used-libraries)
-* [Issues, Ideas And Bugs](#issues-ideas-and-bugs)
-* [License](#license)
-* [Contribution](#contribution)
+[![License](https://img.shields.io/badge/license-bsd-3.svg)](https://choosealicense.com/licenses/bsd-3-clause/) [![Repo Status](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![CI](https://github.com/NewTec-GmbH/pySupersetCli/actions/workflows/ci.yml/badge.svg)](https://github.com/NewTec-GmbH/pySupersetCli/actions/workflows/ci.yml)
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Flags](#flags)
+  - [Login options](#login-options)
+- [Commands](#commands)
+- [Examples](#examples)
+- [Compile into an executable](#compile-into-an-executable)
+- [Used Libraries](#used-libraries)
+- [Issues, Ideas And Bugs](#issues-ideas-and-bugs)
+- [License](#license)
+- [Contribution](#contribution)
+
+## Overview
+
+More information on the deployment and architecture can be found in the [doc](./doc/README.md) folder.
 
 ## Installation
 
@@ -22,31 +29,54 @@ cd pySupersetCli
 pip install .
 ```
 
-## Overview
-
-WIP
-
 ## Usage
 
 Show help information:
 
 ```cmd
-pySupersetCli --help
+pySupersetCli [-h] -u <user> -p <password> -s <server_url> [--version] [-v] [--no_ssl] [--basic_auth] {command} {command_options}
 ```
 
+### Flags
+
+| Flag           | Description                                                                                     |
+| :-----------:  | ----------------------------------------------------------------------------------------------- |
+| --verbose , -v | Print full command details before executing the command. Enables logs of type INFO and WARNING. |
+| --version      | Import a ticket from a JSON file.                                                               |
+| --help , -h    | Show the help message and exit.                                                                 |
+| --no_ssl       | Disables SSL certificate verification.                                                          |
+| --basic_auth   | Use basic authentication instead of LDAP.                                                       |
+
+### Login options
+
+To connect to the Superset server, provide all credentials via Command Line arguments:
+    - `--server <server URL>` is required.
+    - ID using `--user <user>` and `--password <password>`
+
 ## Commands
 
-WIP
+| Command                                     | Description                                         |
+| :-----------------------------------------: | --------------------------------------------------- |
+|[upload](./doc/commands/upload.md)           | Upload a JSON file to a Superset instance.          |
 
 ## Examples
 
 Check out the all the [Examples](./examples) on how to use the pySupersetCli tool.
 
+## Compile into an executable
+
+It is possible to create an executable file that contains the tool and all its dependencies. "PyInstaller" is used for this.
+Just run the following command on the root of the folder:
+
+```cmd
+pyinstaller --noconfirm --onefile --console --name "pySupersetCli" --add-data "./pyproject.toml;."  "./src/pySupersetCli/__main__.py"
+```
+
 ## Used Libraries
 
 Used 3rd party libraries which are not part of the standard Python package:
 
-* [toml](https://github.com/uiri/toml) - Parsing [TOML](https://en.wikipedia.org/wiki/TOML) - MIT License
+- [toml](https://github.com/uiri/toml) - Parsing [TOML](https://en.wikipedia.org/wiki/TOML) - MIT License
 
 ## Issues, Ideas And Bugs
 

doc/README.md

@@ -0,0 +1,9 @@
+# Documentation
+
+## Deployment
+
+![deployment](https://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/NewTec-GmbH/pySupersetCli/main/doc/uml/deployment.puml)
+
+## Architecture
+
+![architecture](https://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/NewTec-GmbH/pySupersetCli/main/doc/uml/architecture.puml)

doc/commands/upload.md

@@ -0,0 +1,19 @@
+# Upload
+
+Upload a JSON file to a Superset instance.
+
+The user mus supply the following parameters:
+
+- database: DB to upload the data to.
+- table: Existing table in the database to save the data to.
+- file: JSON-formatted file containing the data.
+
+```cmd
+pySupersetCli -u <user> -p <password> -s <server_url> --basic_auth --no_ssl upload --database "TEST" --table "dummy" --file "input.json"
+```
+
+## JSON File format
+
+The JSON file must contain a JSON Object, in which the keys are interpreted as the columns of the table. Nested objects are not accepted and the command will fail in case a nested object is supplied. Each time the command is called, a new row will be appended to the database/table specified.
+
+If the table already exists, it is not possible to change the column names/order (no changes in the schema allowed).

doc/uml/architecture.puml

@@ -0,0 +1,20 @@
+@startuml ArchitectureDiagram
+
+package "pySupersetCli" as pySupersetCli {
+    component "Main Entry Point" as main
+    component "superset"as server
+    component "Commands" <<command>> as cmd
+}
+
+package "Python" as python {
+    component "Argparse" as argparse
+    component "Requests" as requests
+}
+
+main *--> server
+main o--> cmd : 0..*
+main *--> argparse
+
+server *--> requests
+
+@enduml

doc/uml/deployment.puml

@@ -0,0 +1,33 @@
+@startuml DeploymentDiagram
+
+node "Apache Superset"<<virtual-machine>> as superset
+
+database "DB Server" {
+    component "Database" as supersetDb
+
+    note bottom of supersetDb
+        The database is project specific, means
+        one database per project.
+    end note
+}
+
+interface "REST API" as supersetRestApi
+
+superset --- supersetRestApi
+superset -- supersetDb
+
+node "Continuous Integration Server"<<virtual-machine>> {
+
+    package "scripts" {
+        component "pySupersetCli" as pySupersetCli
+    }
+}
+
+supersetRestApi )-- pySupersetCli
+
+note top of superset
+    Report frontend for project metrics.
+end note
+
+
+@enduml