You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lens.apache.org by ra...@apache.org on 2015/10/08 11:47:48 UTC
lens git commit: LENS-797: Improve CLI documentation to mention the
helpful role of pressing tab while writing commands
Repository: lens
Updated Branches:
refs/heads/master 7080b76c6 -> 2d7948d72
LENS-797: Improve CLI documentation to mention the helpful role of pressing tab while writing commands
Project: http://git-wip-us.apache.org/repos/asf/lens/repo
Commit: http://git-wip-us.apache.org/repos/asf/lens/commit/2d7948d7
Tree: http://git-wip-us.apache.org/repos/asf/lens/tree/2d7948d7
Diff: http://git-wip-us.apache.org/repos/asf/lens/diff/2d7948d7
Branch: refs/heads/master
Commit: 2d7948d725a4c0444ac04e958e9b2a7ccf2dc59b
Parents: 7080b76
Author: Rajat Khandelwal <pr...@apache.org>
Authored: Thu Oct 8 15:17:23 2015 +0530
Committer: Raju Bairishetti <ra...@im0933-x0.corp.inmobi.com>
Committed: Thu Oct 8 15:17:23 2015 +0530
----------------------------------------------------------------------
.../cli/commands/LensConnectionCommands.java | 2 +-
.../lens/cli/commands/LensCubeCommands.java | 2 +-
.../lens/cli/commands/LensDatabaseCommands.java | 3 +-
.../cli/commands/LensDimensionCommands.java | 3 +-
.../commands/LensDimensionTableCommands.java | 2 +-
.../lens/cli/commands/LensFactCommands.java | 2 +-
.../cli/commands/LensLogResourceCommands.java | 17 ++++----
.../cli/commands/LensNativeTableCommands.java | 2 +-
.../lens/cli/commands/LensQueryCommands.java | 2 +-
.../lens/cli/commands/LensStorageCommands.java | 2 +-
lens-cli/src/test/resources/cli-intro.apt | 23 +++++++---
src/site/apt/user/cli.apt | 45 ++++++++++++--------
12 files changed, 65 insertions(+), 40 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/lens/blob/2d7948d7/lens-cli/src/main/java/org/apache/lens/cli/commands/LensConnectionCommands.java
----------------------------------------------------------------------
diff --git a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensConnectionCommands.java b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensConnectionCommands.java
index 2795211..0aa51a8 100644
--- a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensConnectionCommands.java
+++ b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensConnectionCommands.java
@@ -49,7 +49,7 @@ import lombok.extern.slf4j.Slf4j;
*/
@Slf4j
@Component
-@UserDocumentation(title = "Session management",
+@UserDocumentation(title = "Commands for Session Management",
description = "Opening the lens CLI shell is equivalent to open a session with lens server."
+ "This section provides all the commands available for in shell which are applicable for the full session.")
public class LensConnectionCommands extends BaseLensCommand {
http://git-wip-us.apache.org/repos/asf/lens/blob/2d7948d7/lens-cli/src/main/java/org/apache/lens/cli/commands/LensCubeCommands.java
----------------------------------------------------------------------
diff --git a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensCubeCommands.java b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensCubeCommands.java
index 0afdd61..5211d76 100644
--- a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensCubeCommands.java
+++ b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensCubeCommands.java
@@ -36,7 +36,7 @@ import lombok.NonNull;
* The Class LensCubeCommands.
*/
@Component
-@UserDocumentation(title = "OLAP Data cube metadata management",
+@UserDocumentation(title = "Commands for OLAP Data Cube Management",
description = "These commands provide CRUD for cubes")
public class LensCubeCommands extends ConceptualTableCrudCommand<XCube> {
http://git-wip-us.apache.org/repos/asf/lens/blob/2d7948d7/lens-cli/src/main/java/org/apache/lens/cli/commands/LensDatabaseCommands.java
----------------------------------------------------------------------
diff --git a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensDatabaseCommands.java b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensDatabaseCommands.java
index 1de24a4..05108f0 100644
--- a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensDatabaseCommands.java
+++ b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensDatabaseCommands.java
@@ -31,7 +31,8 @@ import org.springframework.stereotype.Component;
* The Class LensDatabaseCommands.
*/
@Component
-@UserDocumentation(title = "Database management commands", description = "These commands provide CRUD for databases")
+@UserDocumentation(title = "Commands for Database Management",
+ description = "These commands provide CRUD for databases")
public class LensDatabaseCommands extends LensCRUDCommand {
/**
http://git-wip-us.apache.org/repos/asf/lens/blob/2d7948d7/lens-cli/src/main/java/org/apache/lens/cli/commands/LensDimensionCommands.java
----------------------------------------------------------------------
diff --git a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensDimensionCommands.java b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensDimensionCommands.java
index cd7de55..dc8349e 100644
--- a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensDimensionCommands.java
+++ b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensDimensionCommands.java
@@ -36,7 +36,8 @@ import lombok.NonNull;
* The Class LensDimensionCommands.
*/
@Component
-@UserDocumentation(title = "Dimension Management", description = "These commands provide CRUD for Dimensions")
+@UserDocumentation(title = "Commands for Dimension Management",
+ description = "These commands provide CRUD for Dimensions")
public class LensDimensionCommands extends ConceptualTableCrudCommand<XDimension> {
/**
http://git-wip-us.apache.org/repos/asf/lens/blob/2d7948d7/lens-cli/src/main/java/org/apache/lens/cli/commands/LensDimensionTableCommands.java
----------------------------------------------------------------------
diff --git a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensDimensionTableCommands.java b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensDimensionTableCommands.java
index 74efed9..7df5c7c 100644
--- a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensDimensionTableCommands.java
+++ b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensDimensionTableCommands.java
@@ -38,7 +38,7 @@ import lombok.NonNull;
* The Class LensDimensionTableCommands.
*/
@Component
-@UserDocumentation(title = "Commands for Dimension Tables",
+@UserDocumentation(title = "Commands for Dimension Tables Management",
description = "These commands provide CRUD for dimension tables, associated storages, and fact partitions")
public class LensDimensionTableCommands extends LogicalTableCrudCommand<XDimensionTable>
implements CommandMarker {
http://git-wip-us.apache.org/repos/asf/lens/blob/2d7948d7/lens-cli/src/main/java/org/apache/lens/cli/commands/LensFactCommands.java
----------------------------------------------------------------------
diff --git a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensFactCommands.java b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensFactCommands.java
index 6d7d9eb..6457bce 100644
--- a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensFactCommands.java
+++ b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensFactCommands.java
@@ -37,7 +37,7 @@ import lombok.NonNull;
* The Class LensFactCommands.
*/
@Component
-@UserDocumentation(title = "Management of Facts",
+@UserDocumentation(title = "Commands for Facts Management",
description = "These command provide CRUD for facts, associated storages, and fact partitions")
public class LensFactCommands extends LogicalTableCrudCommand<XFactTable> {
http://git-wip-us.apache.org/repos/asf/lens/blob/2d7948d7/lens-cli/src/main/java/org/apache/lens/cli/commands/LensLogResourceCommands.java
----------------------------------------------------------------------
diff --git a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensLogResourceCommands.java b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensLogResourceCommands.java
index c43a5ff..59b7355 100644
--- a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensLogResourceCommands.java
+++ b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensLogResourceCommands.java
@@ -40,29 +40,30 @@ import org.springframework.stereotype.Component;
* SUSPEND CHECKSTYLE CHECK InnerAssignmentCheck
*/
@Component
-@UserDocumentation(title = "Access to Log Resouces",
+@UserDocumentation(title = "Commands for Accessing Logs",
description = "This section provides commands for fetching logs under LENS_LOG_DIR.")
public class LensLogResourceCommands extends BaseLensCommand {
- @CliCommand(value = "show logs", help = "show logs for a given query handle or log file")
+ @CliCommand(value = "show logs",
+ help = "show logs for the given handle <log_handle>. Handle can either be a query handle or request id. "
+ + "You can optionally provide a location to save the logs as <save_location>")
public String getLogs(
- @CliOption(key = {"", "log_handle"}, mandatory = true, help = "log handle can be be query_handle for queries")
+ @CliOption(key = {"", "log_handle"}, mandatory = true, help = "<log_handle>")
String logFile, @CliOption(key = {"save_location"}, mandatory = false, help = "<save_location>") String location) {
try {
Response response = getClient().getLogs(logFile);
if (response.getStatus() == Response.Status.OK.getStatusCode()) {
if (StringUtils.isBlank(location)) {
OutputStream outStream = new PrintStream(System.out, true, "UTF-8");
- try (InputStream stream = response.readEntity(InputStream.class);) {
+ try (InputStream stream = response.readEntity(InputStream.class)) {
IOUtils.copy(stream, outStream);
return "printed complete log content";
}
} else {
- location = getValidPath(new File(location), true, true);
- String fileName = logFile;
- location = getValidPath(new File(location + File.separator + fileName), false, false);
+ String existingDirectoryLocation = getValidPath(new File(location), true, true);
+ location = getValidPath(new File(existingDirectoryLocation + File.separator + logFile), false, false);
try (InputStream stream = response.readEntity(InputStream.class);
- FileOutputStream outStream = new FileOutputStream(new File(location));) {
+ FileOutputStream outStream = new FileOutputStream(new File(location))) {
IOUtils.copy(stream, outStream);
return "Saved to " + location;
}
http://git-wip-us.apache.org/repos/asf/lens/blob/2d7948d7/lens-cli/src/main/java/org/apache/lens/cli/commands/LensNativeTableCommands.java
----------------------------------------------------------------------
diff --git a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensNativeTableCommands.java b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensNativeTableCommands.java
index df42581..32706cf 100644
--- a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensNativeTableCommands.java
+++ b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensNativeTableCommands.java
@@ -32,7 +32,7 @@ import org.springframework.stereotype.Component;
* The Class LensNativeTableCommands.
*/
@Component
-@UserDocumentation(title = "Native Table management", description = "Read operations on native tables")
+@UserDocumentation(title = "Commands for Native Table Management", description = "Read operations on native tables")
public class LensNativeTableCommands extends LensCRUDCommand<XNativeTable> {
/**
http://git-wip-us.apache.org/repos/asf/lens/blob/2d7948d7/lens-cli/src/main/java/org/apache/lens/cli/commands/LensQueryCommands.java
----------------------------------------------------------------------
diff --git a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensQueryCommands.java b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensQueryCommands.java
index b6e3fcf..096fd7a 100644
--- a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensQueryCommands.java
+++ b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensQueryCommands.java
@@ -49,7 +49,7 @@ import com.google.common.base.Joiner;
* SUSPEND CHECKSTYLE CHECK InnerAssignmentCheck
*/
@Component
-@UserDocumentation(title = "Query Management",
+@UserDocumentation(title = "Commands for Query Management",
description = "This section provides commands for query life cycle - "
+ "submit, check status,\n"
+ " fetch results, kill or list all the queries. Also provides commands for\n"
http://git-wip-us.apache.org/repos/asf/lens/blob/2d7948d7/lens-cli/src/main/java/org/apache/lens/cli/commands/LensStorageCommands.java
----------------------------------------------------------------------
diff --git a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensStorageCommands.java b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensStorageCommands.java
index ca73af7..bbda077 100644
--- a/lens-cli/src/main/java/org/apache/lens/cli/commands/LensStorageCommands.java
+++ b/lens-cli/src/main/java/org/apache/lens/cli/commands/LensStorageCommands.java
@@ -36,7 +36,7 @@ import lombok.NonNull;
* The Class LensStorageCommands.
*/
@Component
-@UserDocumentation(title = "Storage Management", description = "These commands provide CRUD for Storages")
+@UserDocumentation(title = "Commands for Storage Management", description = "These commands provide CRUD for Storages")
public class LensStorageCommands extends LensCRUDCommand<XStorage> implements CommandMarker {
@CliCommand(value = "show storages", help = "list all storages")
http://git-wip-us.apache.org/repos/asf/lens/blob/2d7948d7/lens-cli/src/test/resources/cli-intro.apt
----------------------------------------------------------------------
diff --git a/lens-cli/src/test/resources/cli-intro.apt b/lens-cli/src/test/resources/cli-intro.apt
index b5773ab..387e9e1 100644
--- a/lens-cli/src/test/resources/cli-intro.apt
+++ b/lens-cli/src/test/resources/cli-intro.apt
@@ -54,12 +54,6 @@ User CLI Commands
with <<<arg3>>>. arg4 can be omitted, or if passed, it has to be passed with <<<--arg4>>>.
-=========================
-
-
-* LENS Commands
-
-
** Argument Passing in LENS
Lens supports both the approaches of passing arguments but advises the usage of keyword arguments over list arguments.
@@ -72,7 +66,24 @@ User CLI Commands
* Arguments are of any type, but there is only one argument of type arg2 or arg3 and that's the argument you intend
to pass value to.
+
+** About the huge number of commands below
+
+ The commands given below is an exhaustive list of commands available in lens cli. The good thing is, you probably
+ don't need to remember any of them. In lens-cli, pressing <<<tab>>> anytime will give you possible keywords.
+ For example, if you don't know the exact command but have an idea that it's related to facts,
+ type fact and press <<<tab>>>. You'll be provided with all possible next keywords.
+ Looking at the options should be helpful to know which to pick
+ for the action you want to perform. Similarly, when you don't know what arguments the command takes, type <<<-->>>
+ and then <<<tab>>> will also provide you with with the arguments of the command.
+ Also, there's a special command <<<help>>> which displays all possible commands with the arguments they expect.
+
+
** Known bugs
* If all arguments have same value, Something weird will happen.
+================
+
+* LENS CLI Commands
+
http://git-wip-us.apache.org/repos/asf/lens/blob/2d7948d7/src/site/apt/user/cli.apt
----------------------------------------------------------------------
diff --git a/src/site/apt/user/cli.apt b/src/site/apt/user/cli.apt
index be93b8c..c266c6d 100644
--- a/src/site/apt/user/cli.apt
+++ b/src/site/apt/user/cli.apt
@@ -54,12 +54,6 @@ User CLI Commands
with <<<arg3>>>. arg4 can be omitted, or if passed, it has to be passed with <<<--arg4>>>.
-=========================
-
-
-* LENS Commands
-
-
** Argument Passing in LENS
Lens supports both the approaches of passing arguments but advises the usage of keyword arguments over list arguments.
@@ -72,14 +66,31 @@ User CLI Commands
* Arguments are of any type, but there is only one argument of type arg2 or arg3 and that's the argument you intend
to pass value to.
+
+** About the huge number of commands below
+
+ The commands given below is an exhaustive list of commands available in lens cli. The good thing is, you probably
+ don't need to remember any of them. In lens-cli, pressing <<<tab>>> anytime will give you possible keywords.
+ For example, if you don't know the exact command but have an idea that it's related to facts,
+ type fact and press <<<tab>>>. You'll be provided with all possible next keywords.
+ Looking at the options should be helpful to know which to pick
+ for the action you want to perform. Similarly, when you don't know what arguments the command takes, type <<<-->>>
+ and then <<<tab>>> will also provide you with with the arguments of the command.
+ Also, there's a special command <<<help>>> which displays all possible commands with the arguments they expect.
+
+
** Known bugs
* If all arguments have same value, Something weird will happen.
+================
+
+* LENS CLI Commands
+
-** Session management
+** Commands for Session Management
Opening the lens CLI shell is equivalent to open a session with lens server.This section provides all the commands available for in shell which are applicable for the full session.
@@ -114,7 +125,7 @@ User CLI Commands
===
-** Database management commands
+** Commands for Database Management
These commands provide CRUD for databases
@@ -133,7 +144,7 @@ User CLI Commands
===
-** Storage Management
+** Commands for Storage Management
These commands provide CRUD for Storages
@@ -154,7 +165,7 @@ User CLI Commands
===
-** OLAP Data cube metadata management
+** Commands for OLAP Data Cube Management
These commands provide CRUD for cubes
@@ -181,7 +192,7 @@ User CLI Commands
===
-** Dimension Management
+** Commands for Dimension Management
These commands provide CRUD for Dimensions
@@ -206,7 +217,7 @@ User CLI Commands
===
-** Management of Facts
+** Commands for Facts Management
These command provide CRUD for facts, associated storages, and fact partitions
@@ -251,7 +262,7 @@ User CLI Commands
===
-** Commands for Dimension Tables
+** Commands for Dimension Tables Management
These commands provide CRUD for dimension tables, associated storages, and fact partitions
@@ -294,7 +305,7 @@ User CLI Commands
===
-** Native Table management
+** Commands for Native Table Management
Read operations on native tables
@@ -309,7 +320,7 @@ User CLI Commands
===
-** Query Management
+** Commands for Query Management
This section provides commands for query life cycle - submit, check status,
fetch results, kill or list all the queries. Also provides commands for
@@ -354,14 +365,14 @@ User CLI Commands
===
-** Access to Log Resouces
+** Commands for Accessing Logs
This section provides commands for fetching logs under LENS_LOG_DIR.
*--+--+
|<<Command>>|<<Description>>|
*--+--+
-|show logs [--log_handle] log handle can be be query_handle for queries [--save_location \<save_location\>]|show logs for a given query handle or log file|
+|show logs [--log_handle] \<log_handle\> [--save_location \<save_location\>]|show logs for the given handle <<<log_handle>>>. Handle can either be a query handle or request id. You can optionally provide a location to save the logs as <<<save_location>>>|
*--+--+
<<Lens Log Resource Commands>>