Skip to content

Commit 7e0d1ce

Browse files
nightkrnightkr
authored
Add debug command page to docs (#227)
* Automatically generate partials for all subcommands * Add debug command page to docs
1 parent 2af90bd commit 7e0d1ce

File tree

5 files changed

+134
-27
lines changed

5 files changed

+134
-27
lines changed

‎docs/modules/stackablectl/nav.adoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99
*** xref:commands/release.adoc[release]
1010
*** xref:commands/stack.adoc[stack]
1111
*** xref:commands/stacklet.adoc[stacklets]
12+
*** Experimental
13+
**** xref:commands/debug.adoc[debug]
1214
** xref:customization/index.adoc[]
1315
*** xref:customization/add-demo.adoc[]
1416
*** xref:customization/add-stack.adoc[]

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
= stackablectl experimental-debug
2+
3+
IMPORTANT: `debug` is an experimental preview command, and may be changed or removed at any time.
4+
5+
Launches and an ephemeral debug container in a Pod and then attaches to it.
6+
7+
The container will have access to the same data volumes and environment variables as the selected target container.
8+
9+
== General Usage
10+
11+
include::management:stackablectl:partial$commands/experimental-debug.adoc[]

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

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY!
2+
[source,console]
3+
----
4+
EXPERIMENTAL: Launch a debug container for a Pod.
5+
6+
This container will have access to the same data volumes as the primary container.
7+
8+
Usage: stackablectl experimental-debug [OPTIONS] --container <CONTAINER> <POD> [-- <CMD>...]
9+
10+
Arguments:
11+
<POD>
12+
The Pod to debug
13+
14+
[CMD]...
15+
The command to run in the debug container
16+
17+
Options:
18+
-l, --log-level <LOG_LEVEL>
19+
Log level this application uses
20+
21+
-n, --namespace <NAMESPACE>
22+
The namespace of the Pod being debugged
23+
24+
-c, --container <CONTAINER>
25+
The target container to debug
26+
27+
Volumes and environment variables will be copied from this container.
28+
29+
--no-cache
30+
Do not cache the remote (default) demo, stack and release files
31+
32+
Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually
33+
'$HOME/.cache/stackablectl' when not explicitly set.
34+
35+
--image <IMAGE>
36+
The debug container image
37+
38+
Defaults to the image of the target container if not specified.
39+
40+
--offline
41+
Do not request any remote files via the network
42+
43+
-h, --help
44+
Print help (see a summary with '-h')
45+
46+
-V, --version
47+
Print version
48+
49+
File options:
50+
-d, --demo-file <DEMO_FILE>
51+
Provide one or more additional (custom) demo file(s)
52+
53+
Demos are loaded in the following order: Remote (default) demo file, custom
54+
demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and
55+
lastly demo files provided via the '-d/--demo-file' argument(s). If there are
56+
demos with the same name, the last demo definition will be used.
57+
58+
Use "stackablectl [OPTIONS] <COMMAND> -d path/to/demos1.yaml -d path/to/demos2.yaml"
59+
to provide multiple additional demo files.
60+
61+
-s, --stack-file <STACK_FILE>
62+
Provide one or more additional (custom) stack file(s)
63+
64+
Stacks are loaded in the following order: Remote (default) stack file, custom
65+
stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and
66+
lastly demo files provided via the '-s/--stack-file' argument(s). If there are
67+
stacks with the same name, the last stack definition will be used.
68+
69+
Use "stackablectl [OPTIONS] <COMMAND> -s path/to/stacks1.yaml -s path/to/stacks2.yaml"
70+
to provide multiple additional stack files.
71+
72+
-r, --release-file <RELEASE_FILE>
73+
Provide one or more additional (custom) release file(s)
74+
75+
Releases are loaded in the following order: Remote (default) release file,
76+
custom release files provided via the 'STACKABLE_RELEASE_FILES' environment
77+
variable, and lastly release files provided via the '-r/--release-file'
78+
argument(s). If there are releases with the same name, the last release
79+
definition will be used.
80+
81+
Use "stackablectl [OPTIONS] <COMMAND> -r path/to/releases1.yaml -r path/to/releases2.yaml"
82+
to provide multiple additional release files.
83+
84+
Helm repository options:
85+
--helm-repo-stable <URL>
86+
Provide a custom Helm stable repository URL
87+
88+
[default: https://repo.stackable.tech/repository/helm-stable/]
89+
90+
--helm-repo-test <URL>
91+
Provide a custom Helm test repository URL
92+
93+
[default: https://repo.stackable.tech/repository/helm-test/]
94+
95+
--helm-repo-dev <URL>
96+
Provide a custom Helm dev repository URL
97+
98+
[default: https://repo.stackable.tech/repository/helm-dev/]
99+
----

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY!
2+
[source,console]
3+
----
4+
Print this message or the help of the given subcommand(s)
5+
6+
Usage: stackablectl help [COMMAND]
7+
8+
Commands:
9+
operator Interact with single operator instead of the full platform
10+
release Interact with all operators of the platform which are released together
11+
stack Interact with stacks, which are ready-to-use product combinations
12+
stacklet Interact with deployed stacklets, which are bundles of resources and containers required to run the product
13+
demo Interact with demos, which are end-to-end usage demonstrations of the Stackable data platform
14+
completions Generate shell completions for this tool
15+
cache Interact with locally cached files
16+
experimental-debug EXPERIMENTAL: Launch a debug container for a Pod
17+
help Print this message or the help of the given subcommand(s)
18+
----

‎rust/xtask/src/docs.rs

Lines changed: 4 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,6 @@ use clap::CommandFactory;
77
use snafu::{ResultExt, Snafu};
88
use stackablectl::cli::Cli;
99

10-
const COMMANDS: &[&str] = &[
11-
"completions",
12-
"stacklet",
13-
"operator",
14-
"release",
15-
"stack",
16-
"cache",
17-
"demo",
18-
".",
19-
];
20-
2110
const DOCS_BASE_PATH: &str = "docs/modules/stackablectl/partials/commands";
2211

2312
#[derive(Debug, Snafu)]
@@ -44,20 +33,8 @@ pub fn generate() -> Result<(), GenDocsError> {
4433
)
4534
.context(TemplateSnafu)?;
4635

47-
for command_page_name in COMMANDS {
48-
let usage_text = if command_page_name == &"." {
49-
cli.render_long_help().to_string()
50-
} else {
51-
match cli.find_subcommand_mut(command_page_name) {
52-
Some(cmd) => cmd.render_long_help().to_string(),
53-
None => {
54-
return Err(NoSuchSubcommandSnafu {
55-
name: command_page_name.to_string(),
56-
}
57-
.build())
58-
}
59-
}
60-
};
36+
for cmd in cli.get_subcommands().chain([&cli]) {
37+
let usage_text = cmd.clone().render_long_help().to_string();
6138

6239
// Needed to remove trailing whitespaces in empty lines
6340
let usage_text: Vec<_> = usage_text.lines().map(|l| l.trim_end()).collect();
@@ -70,10 +47,10 @@ pub fn generate() -> Result<(), GenDocsError> {
7047
.join(DOCS_BASE_PATH)
7148
.join(format!(
7249
"{}.adoc",
73-
if command_page_name == &"." {
50+
if cmd.get_name() == cli.get_name() {
7451
"index"
7552
} else {
76-
command_page_name
53+
cmd.get_name()
7754
}
7855
));
7956

0 commit comments

Comments
 (0)