Skip to content

Commit d43072f

Browse files
TechassiTechassi
authored
docs: Update management pages (#118)
* Add cache subcommand documentation * Add completions subcommand docs * Update gen-docs xtask * Update command pages * Update stacklet xref * Add conditions hint * Update Cockpit start page * Generate usage docs into antora partial * Re-add correct long help texts The command requires a call to the `build` function. See clap-rs/clap#4685
1 parent 205340e commit d43072f

25 files changed

+786
-603
lines changed

‎.pre-commit-config.yaml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,3 +71,9 @@ repos:
7171
entry: cargo xtask gen-ctl-readme
7272
stages: [commit, merge-commit, manual]
7373
pass_filenames: false
74+
- id: gen-docs
75+
name: gen-docs
76+
language: system
77+
entry: cargo xtask gen-docs
78+
stages: [commit, merge-commit, manual]
79+
pass_filenames: false

‎Cargo.lock

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/modules/cockpit/pages/index.adoc

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
= Stackable Cockpit
22

3-
This is a visual dashboard to monitor and control Stackable Data Platform clusters.
3+
IMPORTANT: The Stackable Cockpit is currently an early preview, and is not yet a fully supported component of the
4+
Stackable Data Platform.
45

5-
IMPORTANT: The Stackable Cockpit is currently an early preview, and is not yet a
6-
fully supported component of the Stackable Data Platform.
6+
The `Cockpit` application is a browser-based management tool which interacts with the Stackable data platform. Currently
7+
it can display deployed stacklets and their status. The display can be compared with the
8+
xref:management:stackablectl:commands/stacklet.adoc#list-stacklets[`stackablectl stacklet list`] command output.
9+
10+
The installation is described in the xref:installation.adoc[installation guide].

‎docs/modules/stackablectl/nav.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
*** xref:commands/operator.adoc[operator]
99
*** xref:commands/release.adoc[release]
1010
*** xref:commands/stack.adoc[stack]
11-
*** xref:commands/stacklets.adoc[stacklets]
11+
*** xref:commands/stacklet.adoc[stacklets]
1212
** xref:customization/index.adoc[]
1313
*** xref:customization/add-demo.adoc[]
1414
*** xref:customization/add-stack.adoc[]

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

Lines changed: 25 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,85 +1,34 @@
11
= stackablectl cache
22

3-
// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY!
4-
[source,console]
5-
----
6-
$ stackablectl cache
7-
Interact with locally cached files
8-
9-
Usage: cache [OPTIONS] <COMMAND>
10-
11-
Commands:
12-
list List cached files
13-
clean Clean cached files
14-
help Print this message or the help of the given subcommand(s)
15-
16-
Options:
17-
-l, --log-level <LOG_LEVEL>
18-
Log level this application uses
19-
20-
--no-cache
21-
Do not cache the remote (default) demo, stack and release files
22-
23-
Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually
24-
'$HOME/.cache/stackablectl' when not explicitly set.
25-
26-
--offline
27-
Do not request any remote files via the network
28-
29-
-h, --help
30-
Print help (see a summary with '-h')
31-
32-
-V, --version
33-
Print version
34-
35-
File options:
36-
-d, --demo-file <DEMO_FILE>
37-
Provide one or more additional (custom) demo file(s)
3+
The `cache` command let's you interact with locally cached files. The `stackablectl` tool retrieves release, demo, and
4+
stack definitions from a dedicated GitHub repository. It additionally retrieves Helm / YAML manifests from various other
5+
sources. These files are downloaded once and then cached for one hour. In this time period, the files are not downloaded
6+
again, but instead the locally cached (stored on disk) files are used. Users can opt out of caching by providing the
7+
`--no-cache` flag.
388

39-
Demos are loaded in the following order: Remote (default) demo file, custom
40-
demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and
41-
lastly demo files provided via the '-d/--demo-file' argument(s). If there are
42-
demos with the same name, the last demo definition will be used.
9+
== General Usage
4310

44-
Use "stackablectl [OPTIONS] <COMMAND> -d path/to/demos1.yaml -d path/to/demos2.yaml"
45-
to provide multiple additional demo files.
11+
include::management:stackablectl:partial$commands/cache.adoc[]
4612

47-
-s, --stack-file <STACK_FILE>
48-
Provide one or more additional (custom) stack file(s)
13+
== Listing Cached Files
4914

50-
Stacks are loaded in the following order: Remote (default) stack file, custom
51-
stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and
52-
lastly demo files provided via the '-s/--stack-file' argument(s). If there are
53-
stacks with the same name, the last stack definition will be used.
15+
To list currently cached files, use `stackablectl cache list`:
5416

55-
Use "stackablectl [OPTIONS] <COMMAND> -s path/to/stacks1.yaml -s path/to/stacks2.yaml"
56-
to provide multiple additional stack files.
57-
58-
-r, --release-file <RELEASE_FILE>
59-
Provide one or more additional (custom) release file(s)
60-
61-
Releases are loaded in the following order: Remote (default) release file,
62-
custom release files provided via the 'STACKABLE_RELEASE_FILES' environment
63-
variable, and lastly release files provided via the '-r/--release-file'
64-
argument(s). If there are releases with the same name, the last release
65-
definition will be used.
66-
67-
Use "stackablectl [OPTIONS] <COMMAND> -r path/to/releases1.yaml -r path/to/releases2.yaml"
68-
to provide multiple additional release files.
69-
70-
Helm repository options:
71-
--helm-repo-stable <URL>
72-
Provide a custom Helm stable repository URL
73-
74-
[default: https://repo.stackable.tech/repository/helm-stable/]
75-
76-
--helm-repo-test <URL>
77-
Provide a custom Helm test repository URL
78-
79-
[default: https://repo.stackable.tech/repository/helm-test/]
17+
[source,console]
18+
----
19+
$ stackablectl cache list
20+
┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬────────────────┐
21+
│ FILE ┆ LAST SYNC │
22+
╞════════════════════════════════════════════════════════════════════════════════════════════════════════════════╪════════════════╡
23+
│ $HOME/.cache/stackablectl/https---raw-githubusercontent-com-stackabletech-stackablectl-main-stacks-stacks-v2-y ┆ 3 seconds ago │
24+
│ aml-17447ade21bb02fe827b33ef32404e7cb3866ee169837dead6dfdcd7f7241e07 ┆ │
25+
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
26+
│ $HOME/.cache/stackablectl/https---raw-githubusercontent-com-stackabletech-stackablectl-main-demos-demos-v2-yam ┆ 22 seconds ago │
27+
│ l-a140c16c241efa6dbee780d48843a1975bd1069ee8dd8f936123ffb8ee700739 ┆ │
28+
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴────────────────┘
29+
----
8030

81-
--helm-repo-dev <URL>
82-
Provide a custom Helm dev repository URL
31+
== Cleaning Cached Files
8332

84-
[default: https://repo.stackable.tech/repository/helm-dev/]
85-
----
33+
To clean currently cached files, use `stackablectl cache clean`. This will remove **all** cached files, regardless if
34+
the files are expired. To only delete outdated files, add the `--outdated` flag.

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

Lines changed: 3 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,86 +1,6 @@
11
= stackablectl completions
22

3-
// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY!
4-
[source,console]
5-
----
6-
$ stackablectl completions
7-
Generate shell completions for this tool
3+
The `completions` command allows you to generate shell completions on-the-fly. Usually this is not needed, as we provide
4+
pre-generated files for that. A guide on how to install these files can be found xref:installation.adoc#shell-comps[here].
85

9-
Usage: completions [OPTIONS] <COMMAND>
10-
11-
Commands:
12-
bash Generate shell completions for Bash
13-
fish Generate shell completions for Fish
14-
zsh Generate shell completions for ZSH
15-
help Print this message or the help of the given subcommand(s)
16-
17-
Options:
18-
-l, --log-level <LOG_LEVEL>
19-
Log level this application uses
20-
21-
--no-cache
22-
Do not cache the remote (default) demo, stack and release files
23-
24-
Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually
25-
'$HOME/.cache/stackablectl' when not explicitly set.
26-
27-
--offline
28-
Do not request any remote files via the network
29-
30-
-h, --help
31-
Print help (see a summary with '-h')
32-
33-
-V, --version
34-
Print version
35-
36-
File options:
37-
-d, --demo-file <DEMO_FILE>
38-
Provide one or more additional (custom) demo file(s)
39-
40-
Demos are loaded in the following order: Remote (default) demo file, custom
41-
demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and
42-
lastly demo files provided via the '-d/--demo-file' argument(s). If there are
43-
demos with the same name, the last demo definition will be used.
44-
45-
Use "stackablectl [OPTIONS] <COMMAND> -d path/to/demos1.yaml -d path/to/demos2.yaml"
46-
to provide multiple additional demo files.
47-
48-
-s, --stack-file <STACK_FILE>
49-
Provide one or more additional (custom) stack file(s)
50-
51-
Stacks are loaded in the following order: Remote (default) stack file, custom
52-
stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and
53-
lastly demo files provided via the '-s/--stack-file' argument(s). If there are
54-
stacks with the same name, the last stack definition will be used.
55-
56-
Use "stackablectl [OPTIONS] <COMMAND> -s path/to/stacks1.yaml -s path/to/stacks2.yaml"
57-
to provide multiple additional stack files.
58-
59-
-r, --release-file <RELEASE_FILE>
60-
Provide one or more additional (custom) release file(s)
61-
62-
Releases are loaded in the following order: Remote (default) release file,
63-
custom release files provided via the 'STACKABLE_RELEASE_FILES' environment
64-
variable, and lastly release files provided via the '-r/--release-file'
65-
argument(s). If there are releases with the same name, the last release
66-
definition will be used.
67-
68-
Use "stackablectl [OPTIONS] <COMMAND> -r path/to/releases1.yaml -r path/to/releases2.yaml"
69-
to provide multiple additional release files.
70-
71-
Helm repository options:
72-
--helm-repo-stable <URL>
73-
Provide a custom Helm stable repository URL
74-
75-
[default: https://repo.stackable.tech/repository/helm-stable/]
76-
77-
--helm-repo-test <URL>
78-
Provide a custom Helm test repository URL
79-
80-
[default: https://repo.stackable.tech/repository/helm-test/]
81-
82-
--helm-repo-dev <URL>
83-
Provide a custom Helm dev repository URL
84-
85-
[default: https://repo.stackable.tech/repository/helm-dev/]
86-
----
6+
include::management:stackablectl:partial$commands/completions.adoc[]

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

Lines changed: 2 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -6,90 +6,7 @@ Stackable data platform, which will provide the required products for the demo.
66

77
== General Usage
88

9-
// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY!
10-
[source,console]
11-
----
12-
$ stackablectl demo
13-
Interact with demos, which are end-to-end usage demonstrations of the Stackable data platform
14-
15-
Usage: demo [OPTIONS] <COMMAND>
16-
17-
Commands:
18-
list List available demos
19-
describe Print out detailed demo information
20-
install Install a specific demo
21-
help Print this message or the help of the given subcommand(s)
22-
23-
Options:
24-
-l, --log-level <LOG_LEVEL>
25-
Log level this application uses
26-
27-
--no-cache
28-
Do not cache the remote (default) demo, stack and release files
29-
30-
Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually
31-
'$HOME/.cache/stackablectl' when not explicitly set.
32-
33-
--offline
34-
Do not request any remote files via the network
35-
36-
-h, --help
37-
Print help (see a summary with '-h')
38-
39-
-V, --version
40-
Print version
41-
42-
File options:
43-
-d, --demo-file <DEMO_FILE>
44-
Provide one or more additional (custom) demo file(s)
45-
46-
Demos are loaded in the following order: Remote (default) demo file, custom
47-
demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and
48-
lastly demo files provided via the '-d/--demo-file' argument(s). If there are
49-
demos with the same name, the last demo definition will be used.
50-
51-
Use "stackablectl [OPTIONS] <COMMAND> -d path/to/demos1.yaml -d path/to/demos2.yaml"
52-
to provide multiple additional demo files.
53-
54-
-s, --stack-file <STACK_FILE>
55-
Provide one or more additional (custom) stack file(s)
56-
57-
Stacks are loaded in the following order: Remote (default) stack file, custom
58-
stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and
59-
lastly demo files provided via the '-s/--stack-file' argument(s). If there are
60-
stacks with the same name, the last stack definition will be used.
61-
62-
Use "stackablectl [OPTIONS] <COMMAND> -s path/to/stacks1.yaml -s path/to/stacks2.yaml"
63-
to provide multiple additional stack files.
64-
65-
-r, --release-file <RELEASE_FILE>
66-
Provide one or more additional (custom) release file(s)
67-
68-
Releases are loaded in the following order: Remote (default) release file,
69-
custom release files provided via the 'STACKABLE_RELEASE_FILES' environment
70-
variable, and lastly release files provided via the '-r/--release-file'
71-
argument(s). If there are releases with the same name, the last release
72-
definition will be used.
73-
74-
Use "stackablectl [OPTIONS] <COMMAND> -r path/to/releases1.yaml -r path/to/releases2.yaml"
75-
to provide multiple additional release files.
76-
77-
Helm repository options:
78-
--helm-repo-stable <URL>
79-
Provide a custom Helm stable repository URL
80-
81-
[default: https://repo.stackable.tech/repository/helm-stable/]
82-
83-
--helm-repo-test <URL>
84-
Provide a custom Helm test repository URL
85-
86-
[default: https://repo.stackable.tech/repository/helm-test/]
87-
88-
--helm-repo-dev <URL>
89-
Provide a custom Helm dev repository URL
90-
91-
[default: https://repo.stackable.tech/repository/helm-dev/]
92-
----
9+
include::management:stackablectl:partial$commands/demo.adoc[]
9310

9411
== Browse Available Demos
9512

@@ -228,7 +145,7 @@ everything should settle down.
228145

229146
=== Listing Deployed Stacklets
230147

231-
After installing your demo you can use the xref:commands/stacklets.adoc[`stackablectl stacklets`] command to list the
148+
After installing your demo you can use the xref:commands/stacklet.adoc[`stackablectl stacklets`] command to list the
232149
installed stacklets as follows:
233150

234151
[source,console]

0 commit comments

Comments
 (0)