Add debug command page to docs (#227)

* Automatically generate partials for all subcommands

* Add debug command page to docs

docs/modules/stackablectl/nav.adoc

@@ -9,6 +9,8 @@
 *** xref:commands/release.adoc[release]
 *** xref:commands/stack.adoc[stack]
 *** xref:commands/stacklet.adoc[stacklets]
+*** Experimental
+**** xref:commands/debug.adoc[debug]
 ** xref:customization/index.adoc[]
 *** xref:customization/add-demo.adoc[]
 *** xref:customization/add-stack.adoc[]

docs/modules/stackablectl/pages/commands/debug.adoc

@@ -0,0 +1,11 @@
+= stackablectl experimental-debug
+
+IMPORTANT: `debug` is an experimental preview command, and may be changed or removed at any time.
+
+Launches and an ephemeral debug container in a Pod and then attaches to it.
+
+The container will have access to the same data volumes and environment variables as the selected target container.
+
+== General Usage
+
+include::management:stackablectl:partial$commands/experimental-debug.adoc[]

docs/modules/stackablectl/partials/commands/experimental-debug.adoc

@@ -0,0 +1,99 @@
+// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY!
+[source,console]
+----
+EXPERIMENTAL: Launch a debug container for a Pod.
+
+This container will have access to the same data volumes as the primary container.
+
+Usage: stackablectl experimental-debug [OPTIONS] --container <CONTAINER> <POD> [-- <CMD>...]
+
+Arguments:
+  <POD>
+          The Pod to debug
+
+  [CMD]...
+          The command to run in the debug container
+
+Options:
+  -l, --log-level <LOG_LEVEL>
+          Log level this application uses
+
+  -n, --namespace <NAMESPACE>
+          The namespace of the Pod being debugged
+
+  -c, --container <CONTAINER>
+          The target container to debug
+
+          Volumes and environment variables will be copied from this container.
+
+      --no-cache
+          Do not cache the remote (default) demo, stack and release files
+
+          Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually
+          '$HOME/.cache/stackablectl' when not explicitly set.
+
+      --image <IMAGE>
+          The debug container image
+
+          Defaults to the image of the target container if not specified.
+
+      --offline
+          Do not request any remote files via the network
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+  -V, --version
+          Print version
+
+File options:
+  -d, --demo-file <DEMO_FILE>
+          Provide one or more additional (custom) demo file(s)
+
+          Demos are loaded in the following order: Remote (default) demo file, custom
+          demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and
+          lastly demo files provided via the '-d/--demo-file' argument(s). If there are
+          demos with the same name, the last demo definition will be used.
+
+          Use "stackablectl [OPTIONS] <COMMAND> -d path/to/demos1.yaml -d path/to/demos2.yaml"
+          to provide multiple additional demo files.
+
+  -s, --stack-file <STACK_FILE>
+          Provide one or more additional (custom) stack file(s)
+
+          Stacks are loaded in the following order: Remote (default) stack file, custom
+          stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and
+          lastly demo files provided via the '-s/--stack-file' argument(s). If there are
+          stacks with the same name, the last stack definition will be used.
+
+          Use "stackablectl [OPTIONS] <COMMAND> -s path/to/stacks1.yaml -s path/to/stacks2.yaml"
+          to provide multiple additional stack files.
+
+  -r, --release-file <RELEASE_FILE>
+          Provide one or more additional (custom) release file(s)
+
+          Releases are loaded in the following order: Remote (default) release file,
+          custom release files provided via the 'STACKABLE_RELEASE_FILES' environment
+          variable, and lastly release files provided via the '-r/--release-file'
+          argument(s). If there are releases with the same name, the last release
+          definition will be used.
+
+          Use "stackablectl [OPTIONS] <COMMAND> -r path/to/releases1.yaml -r path/to/releases2.yaml"
+          to provide multiple additional release files.
+
+Helm repository options:
+      --helm-repo-stable <URL>
+          Provide a custom Helm stable repository URL
+
+          [default: https://repo.stackable.tech/repository/helm-stable/]
+
+      --helm-repo-test <URL>
+          Provide a custom Helm test repository URL
+
+          [default: https://repo.stackable.tech/repository/helm-test/]
+
+      --helm-repo-dev <URL>
+          Provide a custom Helm dev repository URL
+
+          [default: https://repo.stackable.tech/repository/helm-dev/]
+----

docs/modules/stackablectl/partials/commands/help.adoc

@@ -0,0 +1,18 @@
+// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY!
+[source,console]
+----
+Print this message or the help of the given subcommand(s)
+
+Usage: stackablectl help [COMMAND]
+
+Commands:
+  operator            Interact with single operator instead of the full platform
+  release             Interact with all operators of the platform which are released together
+  stack               Interact with stacks, which are ready-to-use product combinations
+  stacklet            Interact with deployed stacklets, which are bundles of resources and containers required to run the product
+  demo                Interact with demos, which are end-to-end usage demonstrations of the Stackable data platform
+  completions         Generate shell completions for this tool
+  cache               Interact with locally cached files
+  experimental-debug  EXPERIMENTAL: Launch a debug container for a Pod
+  help                Print this message or the help of the given subcommand(s)
+----

rust/xtask/src/docs.rs

@@ -7,17 +7,6 @@ use clap::CommandFactory;
 use snafu::{ResultExt, Snafu};
 use stackablectl::cli::Cli;
 
-const COMMANDS: &[&str] = &[
-    "completions",
-    "stacklet",
-    "operator",
-    "release",
-    "stack",
-    "cache",
-    "demo",
-    ".",
-];
-
 const DOCS_BASE_PATH: &str = "docs/modules/stackablectl/partials/commands";
 
 #[derive(Debug, Snafu)]
@@ -44,20 +33,8 @@ pub fn generate() -> Result<(), GenDocsError> {
         )
         .context(TemplateSnafu)?;
 
-    for command_page_name in COMMANDS {
-        let usage_text = if command_page_name == &"." {
-            cli.render_long_help().to_string()
-        } else {
-            match cli.find_subcommand_mut(command_page_name) {
-                Some(cmd) => cmd.render_long_help().to_string(),
-                None => {
-                    return Err(NoSuchSubcommandSnafu {
-                        name: command_page_name.to_string(),
-                    }
-                    .build())
-                }
-            }
-        };
+    for cmd in cli.get_subcommands().chain([&cli]) {
+        let usage_text = cmd.clone().render_long_help().to_string();
 
         // Needed to remove trailing whitespaces in empty lines
         let usage_text: Vec<_> = usage_text.lines().map(|l| l.trim_end()).collect();
@@ -70,10 +47,10 @@ pub fn generate() -> Result<(), GenDocsError> {
             .join(DOCS_BASE_PATH)
             .join(format!(
                 "{}.adoc",
-                if command_page_name == &"." {
+                if cmd.get_name() == cli.get_name() {
                     "index"
                 } else {
-                    command_page_name
+                    cmd.get_name()
                 }
             ));