From 7e0d1ce3abc878babedd0c6c034a2ffffcbf6cdb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Natalie=20Klestrup=20R=C3=B6ijezon?= Date: Thu, 4 Apr 2024 16:36:21 +0200 Subject: [PATCH] Add debug command page to docs (#227) * Automatically generate partials for all subcommands * Add debug command page to docs --- docs/modules/stackablectl/nav.adoc | 2 + .../stackablectl/pages/commands/debug.adoc | 11 +++ .../partials/commands/experimental-debug.adoc | 99 +++++++++++++++++++ .../stackablectl/partials/commands/help.adoc | 18 ++++ rust/xtask/src/docs.rs | 31 +----- 5 files changed, 134 insertions(+), 27 deletions(-) create mode 100644 docs/modules/stackablectl/pages/commands/debug.adoc create mode 100644 docs/modules/stackablectl/partials/commands/experimental-debug.adoc create mode 100644 docs/modules/stackablectl/partials/commands/help.adoc diff --git a/docs/modules/stackablectl/nav.adoc b/docs/modules/stackablectl/nav.adoc index a67dfb4c..b57cb95c 100644 --- a/docs/modules/stackablectl/nav.adoc +++ b/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[] diff --git a/docs/modules/stackablectl/pages/commands/debug.adoc b/docs/modules/stackablectl/pages/commands/debug.adoc new file mode 100644 index 00000000..c304ce0f --- /dev/null +++ b/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[] diff --git a/docs/modules/stackablectl/partials/commands/experimental-debug.adoc b/docs/modules/stackablectl/partials/commands/experimental-debug.adoc new file mode 100644 index 00000000..7da60f15 --- /dev/null +++ b/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 [-- ...] + +Arguments: + + The Pod to debug + + [CMD]... + The command to run in the debug container + +Options: + -l, --log-level + Log level this application uses + + -n, --namespace + The namespace of the Pod being debugged + + -c, --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 + 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 + 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] -d path/to/demos1.yaml -d path/to/demos2.yaml" + to provide multiple additional demo files. + + -s, --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] -s path/to/stacks1.yaml -s path/to/stacks2.yaml" + to provide multiple additional stack files. + + -r, --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] -r path/to/releases1.yaml -r path/to/releases2.yaml" + to provide multiple additional release files. + +Helm repository options: + --helm-repo-stable + Provide a custom Helm stable repository URL + + [default: https://repo.stackable.tech/repository/helm-stable/] + + --helm-repo-test + Provide a custom Helm test repository URL + + [default: https://repo.stackable.tech/repository/helm-test/] + + --helm-repo-dev + Provide a custom Helm dev repository URL + + [default: https://repo.stackable.tech/repository/helm-dev/] +---- diff --git a/docs/modules/stackablectl/partials/commands/help.adoc b/docs/modules/stackablectl/partials/commands/help.adoc new file mode 100644 index 00000000..6a390f6f --- /dev/null +++ b/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) +---- diff --git a/rust/xtask/src/docs.rs b/rust/xtask/src/docs.rs index c13f5f94..df2869f9 100644 --- a/rust/xtask/src/docs.rs +++ b/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() } ));