feat: improve cli tools and docs (#803)

* docs(cli): improve descriptions and output of CLI commands Signed-off-by: Chris Laprun <claprun@redhat.com> * docs(cli): add help option to api command Signed-off-by: Chris Laprun <claprun@redhat.com> * docs: add information on CLI / Dev mode commands Signed-off-by: Chris Laprun <claprun@redhat.com> --------- Signed-off-by: Chris Laprun <claprun@redhat.com>
quarkiverse · Jan 22, 2024 · 413e376 · 413e376
1 parent 017b47c
commit 413e376
Show file tree

Hide file tree

Showing 4 changed files with 31 additions and 17 deletions.
diff --git a/common/src/main/java/io/quarkiverse/operatorsdk/common/CLIConstants.java b/common/src/main/java/io/quarkiverse/operatorsdk/common/CLIConstants.java
@@ -5,15 +5,15 @@ public class CLIConstants {
 
     public static final char API_KIND_SHORT = 'k';
     public static final String API_KIND = "kind";
-    public static final String API_KIND_DESCRIPTION = "Your API's kind";
+    public static final String API_KIND_DESCRIPTION = "Your API's kind, used to generate a CustomResource class with associated spec, status and Reconciler classes";
 
     public static final char API_VERSION_SHORT = 'v';
     public static final String API_VERSION = "version";
-    public static final String API_VERSION_DESCRIPTION = "Your API's version";
+    public static final String API_VERSION_DESCRIPTION = "Your API's version, e.g. v1beta1";
 
     public static final char API_GROUP_SHORT = 'g';
     public static final String API_GROUP = "group";
-    public static final String API_GROUP_DESCRIPTION = "Your API's group, this will also be used as package name for the generated classes";
+    public static final String API_GROUP_DESCRIPTION = "Your API's group, e.g. halkyon.io, this will also be used, reversed, as package name for the generated classes";
 
     private CLIConstants() {
     }

diff --git a/...oyment/src/main/java/io/quarkiverse/operatorsdk/deployment/devui/commands/APICommand.java b/...oyment/src/main/java/io/quarkiverse/operatorsdk/deployment/devui/commands/APICommand.java
@@ -23,13 +23,21 @@ public class APICommand implements Command {
     @Option(name = CLIConstants.API_VERSION, shortName = CLIConstants.API_VERSION_SHORT, description = CLIConstants.API_VERSION_DESCRIPTION, required = true)
     private String version;
 
+    @Option(shortName = 'h', hasValue = false, overrideRequired = true)
+    public boolean help;
+
     @Override
     public CommandResult execute(CommandInvocation commandInvocation) throws CommandException, InterruptedException {
-        return Files.generateAPIFiles(group, version, kind, new Files.MessageWriter() {
-            @Override
-            public void write(String message, Exception e, boolean forError) {
-                commandInvocation.println(formatMessageWithException(message, e));
-            }
-        }) ? CommandResult.SUCCESS : CommandResult.FAILURE;
+        if (this.help) {
+            commandInvocation.getShell().write(commandInvocation.getHelpInfo());
+            return CommandResult.SUCCESS;
+        } else {
+            return Files.generateAPIFiles(group, version, kind, new Files.MessageWriter() {
+                @Override
+                public void write(String message, Exception e, boolean forError) {
+                    commandInvocation.println(formatMessageWithException(message, e));
+                }
+            }) ? CommandResult.SUCCESS : CommandResult.FAILURE;
+        }
     }
 }
diff --git a/...t/src/main/java/io/quarkiverse/operatorsdk/deployment/devui/commands/VersionsCommand.java b/...t/src/main/java/io/quarkiverse/operatorsdk/deployment/devui/commands/VersionsCommand.java
@@ -7,7 +7,7 @@
 
 import io.quarkiverse.operatorsdk.runtime.Version;
 
-@CommandDefinition(name = "versions", description = "Outputs Quarkus, Fabric8, QOSDK and JOSDK versions")
+@CommandDefinition(name = "versions", description = "Outputs QOSDK, Quarkus, Fabric8 and JOSDK versions, with which this QOSDK version was built")
 @SuppressWarnings("rawtypes")
 public class VersionsCommand implements Command {
 
@@ -19,8 +19,8 @@ public VersionsCommand(Version version) {
 
     @Override
     public CommandResult execute(CommandInvocation commandInvocation) {
-        String output = "Quarkus version: " + version.getQuarkusVersion() + "\n" +
-                "Fabric8 client version: " + version.getKubernetesClientVersion() + "\n" +
+        String output = "Targeted Quarkus version: " + version.getQuarkusVersion() + "\n" +
+                "Fabric8 client version targeted by JOSDK: " + version.getKubernetesClientVersion() + "\n" +
                 "QOSDK version: " + version.getExtensionCompleteVersion() + "\n" +
                 "JOSDK version: " + version.getSdkVersion();
         commandInvocation.println(output);

diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
@@ -18,15 +18,21 @@ Please also refer to the https://javaoperatorsdk.io/docs/getting-started[JOSDK d
 - Automatically generates Kubernetes descriptors
 - Automatically generates the bundle manifests for all reconcilers (using the `quarkus-operator-sdk-bundle-generator` extension)
 - Integrates with the Dev mode:
-* Watches your code for changes and reload automatically your operator if needed without having to hit an endpoint
-* Only re-generates the CRDs if a change impacting its generation is detected
-* Only re-processes a reconciler's configuration if needed
-* Automatically apply the CRD to the cluster when it has changed
+    * Watches your code for changes and reload automatically your operator if needed without having to hit an endpoint
+    * Only re-generates the CRDs if a change impacting its generation is detected
+    * Only re-processes a reconciler's configuration if needed
+    * Automatically apply the CRD to the cluster when it has changed
 - Supports micrometer registry extensions (adding a Quarkus-supported micrometer registry extension will automatically inject said registry into the operator)
 - Automatically adds a SmallRye health check
 - Sets up reflection for native binary generation
 - [Deprecated] Customize the JSON serialization that the Fabric8 client relies on by providing an `ObjectMapperCustomizer` implementation, qualified with the `@KubernetesClientSerializationCustomizer` annotation
-* The Quarkus kubernetes client extension now provides an official mechanism to do so by implementing the `io.quarkus.kubernetes.client.KubernetesClientObjectMapperCustomizer` interface instead so this mechanism should be used moving forward.
+    * The Quarkus kubernetes client extension now provides an official mechanism to do so by implementing the `io.quarkus.kubernetes.client.KubernetesClientObjectMapperCustomizer` interface instead so this mechanism should be used moving forward.
+- Dev mode commands:
+    * Dev commands are automatically accessible from the Dev console after typing `:` in the Quarkus terminal in Dev mode, under the `qosdk` name. Two commands currently exist: `qosdk api` to create a Kubernetes API (hint: type `qosdk api -h` for more details) and `qosdk versions` to show which versions are targeted by QOSDK.
+- CLI command:
+    * Add the Quarkus CLI command using: `quarkus plug add io.quarkiverse.operatorsdk:quarkus-operator-sdk-cli:runner:jar:{project-version}`
+    * You can create a Kubernetes API using the `quarkus operator-sdk api` command, e.g. `quarkus operator-sdk api -g halkyon.io -v v1 -k foo`
+
 
 == Installation