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/current-release-line Commit: 2d7948d725a4c0444ac04e958e9b2a7ccf2dc59b Parents: 7080b76 Author: Rajat Khandelwal <[email protected]> Authored: Thu Oct 8 15:17:23 2015 +0530 Committer: Raju Bairishetti <[email protected]> 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>>
