more documentation (#936)

* more documentation * Update src/server/cli/options.ts Co-authored-by: Marcin Kuthan <marcin.kuthan@allegro.pl> * Update src/server/cli.ts Co-authored-by: Marcin Kuthan <marcin.kuthan@allegro.pl> * Update README.md Co-authored-by: Marcin Kuthan <marcin.kuthan@allegro.pl> * Update README.md Co-authored-by: Piotr Szczepanik <piter75@gmail.com> * update more docs Co-authored-by: Marcin Kuthan <marcin.kuthan@allegro.pl> Co-authored-by: Piotr Szczepanik <piter75@gmail.com>
allegro · Nov 15, 2022 · 3e36fd6 · 3e36fd6
1 parent 30bf5ce
commit 3e36fd6
Show file tree

Hide file tree

Showing 4 changed files with 52 additions and 25 deletions.
diff --git a/README.md b/README.md
@@ -72,18 +72,18 @@ Install Turnilo distribution using [npm](https://www.npmjs.com/).
 npm install -g turnilo
 ```
 
-Start off by running an example with Covid-19 and Wikipedia datasets
+Start off by running Turnilo with example datasets
 and open [http://localhost:9090/](http://localhost:9090/).
 
 ```
-turnilo --examples
+turnilo run-examples
 ```
 
-Or connect to the existing Druid broker using `--druid` command line option.
+Use `connect-druid` command to connect to the existing Druid broker.
 Turnilo will automatically introspect your Druid broker and figure out available datasets.
 
 ```
-turnilo --druid http[s]://druid-broker-hostname[:port]
+turnilo connect-druid http[s]://druid-broker-hostname[:port]
 ```
 
 ## Documentation
@@ -107,7 +107,7 @@ npm run build
 
 ### Run project
 
-Run Covid-19 and Wikipedia examples.
+Run example datasets.
 
 ```
 npm run start:examples
@@ -116,20 +116,20 @@ npm run start:examples
 Connect to the existing Druid broker.
 
 ```
-npm run start -- --druid http[s]://druid-broker-hostname[:port]
+npm run start -- connect-druid http[s]://druid-broker-hostname[:port]
 ```
 
 Connect to the existing Druid broker using your config file.
 
 ```
-npm run start -- --config path/to/config.yml
+npm run start -- run-config path/to/config.yml
 ```
 
 ### Run project in developer mode
 
 Every change in frontend code would recompile project and reload page.
 
-Run Covid-19 and Wikipedia examples.
+Run example datasets.
 
 ```
 npm run start:dev:examples
@@ -138,13 +138,13 @@ npm run start:dev:examples
 Connect to the existing Druid broker.
 
 ```
-npm run start:dev -- --druid http[s]://druid-broker-hostname[:port]
+npm run start:dev -- connect-druid http[s]://druid-broker-hostname[:port]
 ```
 
 Connect to the existing Druid broker using your config file.
 
 ```
-npm run start:dev -- --config path/to/config.yml
+npm run start:dev -- run-config path/to/config.yml
 ```
 
 

diff --git a/docs/configuration-cluster.md b/docs/configuration-cluster.md
@@ -6,7 +6,7 @@ layout: page
 
 ## Overview
 
-It is easy to start using Turnilo with Druid by pointing it at your Druid cluster: `turnilo --druid broker_host:broker_port`
+It is easy to start using Turnilo with Druid by pointing it at your Druid cluster: `turnilo connect-druid broker_host:broker_port`
 Turnilo will automatically introspect your Druid cluster and figure out available datasets.
 
 Turnilo can be configured with a *config* YAML file. While you could write one from scratch it is recommended to let
@@ -15,13 +15,13 @@ Turnilo give you a head start by using it to generate a config file for you usin
 Run:
 
 ```bash
-turnilo --druid broker_host:broker_port --print-config --with-comments > config.yaml
+turnilo introspect-druid broker_host:broker_port --verbose > config.yaml
 ```
 
 This will cause Turnilo to go through its normal startup and introspection routine and then dump the internally generated
 config (complete with comments) into the provided file.
 
-You can now run `turnilo --config config.yaml` to run Turnilo with your config.
+You can now run `turnilo run-config config.yaml` to run Turnilo with your config.
 
 The next step is to open the generated config file in your favourite text editor and configure Turnilo to your liking.
 Below we will go through a typical configuration flow. At any point you can save the config and re-launch Turnilo to load

diff --git a/src/server/cli.ts b/src/server/cli.ts
@@ -45,7 +45,8 @@ program
 
 program
   .command("run-config")
-  .argument("<file>", "path of config file")
+  .description("Runs Turnilo using config file")
+  .argument("<config-path>", "Path to config file")
   .addOption(portOption)
   .addOption(serverRootOption)
   .addOption(serverHostOption)
@@ -74,6 +75,7 @@ program
 
 program
   .command("run-examples")
+  .description("Runs Turnilo with example datasets")
   .addOption(portOption)
   .addOption(serverRootOption)
   .addOption(serverHostOption)
@@ -95,7 +97,8 @@ program
 
 program
   .command("connect-druid")
-  .argument("<url>", "druid url")
+  .description("Runs turnilo that connects to Druid cluster and introspects it for datasets")
+  .argument("<druid-url>", "Url of Druid cluster")
   .addOption(portOption)
   .addOption(serverRootOption)
   .addOption(serverHostOption)
@@ -116,8 +119,9 @@ program
 
 program
   .command("load-file")
-  .argument("<file>", "json file")
-  .requiredOption("-t, --time-attribute <attribute>", "time attribute")
+  .description("Runs Turnilo and loads json file as a dataset")
+  .argument("<file-path>", "Path to json file with data")
+  .requiredOption("-t, --time-attribute <field-name>", "JSON field name with time column")
   .addOption(portOption)
   .addOption(serverRootOption)
   .addOption(serverHostOption)
@@ -140,7 +144,8 @@ program
 
 program
   .command("verify-config")
-  .argument("<file>", "path to config file")
+  .description("Runs verification of provided config file")
+  .argument("<file-path>", "Path to config file to verify")
   .addOption(verboseOption)
   .action((file, { verbose }) => {
     try {
@@ -153,7 +158,8 @@ program
 
 program
   .command("introspect-druid")
-  .argument("<url>", "druid url")
+  .description("Connects to Druid cluster and prints introspected data in config file format")
+  .argument("<druid-url>", "Url of Druid cluster")
   .addOption(verboseOption)
   .addOption(usernameOption)
   .addOption(passwordOption)

diff --git a/src/server/cli/options.ts b/src/server/cli/options.ts
@@ -15,11 +15,32 @@
  */
 
 import { Option } from "commander";
+import { DEFAULT_PORT } from "../models/server-settings/server-settings";
 import { parseInteger } from "./utils";
 
-export const portOption = new Option("-p, --port <number>", "port number").argParser(parseInteger);
-export const serverRootOption = new Option("--server-root <root>", "server root");
-export const serverHostOption = new Option("--server-host <host>", "server host");
-export const verboseOption = new Option("--verbose", "verbose mode");
-export const usernameOption = new Option("--username <username>", "username");
-export const passwordOption = new Option("--password <password>", "password");
+export const portOption = new Option(
+  "-p, --port <number>",
+  `Port number to start server on. Default: ${DEFAULT_PORT}`
+).argParser(parseInteger);
+
+export const serverRootOption = new Option(
+  "--server-root <path>",
+  "Custom path to act as turnilo root"
+);
+export const serverHostOption = new Option(
+  "--server-host <hostname>",
+  "Host that server will bind to"
+);
+export const verboseOption = new Option(
+  "--verbose",
+  "Verbose mode"
+);
+
+export const usernameOption = new Option(
+  "--username <username>",
+  "Username that will be used in HTTP Basic authentication to Druid cluster"
+);
+export const passwordOption = new Option(
+  "--password <password>",
+  "Password that will be used in HTTP Basic authentication to Druid cluster"
+);