docs: Update and improve stackablectl documentation (#101)

* Initial commit

* Add demos partial

* Split up xtask commands

* Add doc auto gen xtask

* Adjust module nav

* Adjust operator cmd output, fix typo

* Update operator doc page

* Continue release doc page

* Revert to `rustls-tls`

* Continue stackablectl demos doc migration

* Copy earthquake demo docs

* Copy logging demo page

* Copy waterlavel demo docs

* Move demo images to sub folder

* Add anomaly detection demo docs

* Copy trino iceberg demo docs

* Copy trino taxi data demo docs

* Update docs auto generation

* Add stackablectl base command docs

* Update image paths

* Add customization docs

* Add quickstart

* Add minor adjustments

* Style adjustment for start page

* Add quickstart and installation page to nav

* Adjust style for demo command page

* Adjust style for operator command page

* Adjust style for release command page

* Adjust style for airflow-scheduled-job page

* Update introduction for operator command

* Start styling adjustments for demo data-lakehouse

* Continue adjustments on data-lakehouse demo

* Finish data-lakehouse demo adjustments

* Add instance hint partial

* Adjust hbase-cycling-data demo

* Adjust jupyterhub demo

* Adjust logging demo

* Start adjustments for nifi earthquake demo

* Adjust spark anomaly detection docs

* Adjust add demo customization docs

* Adjust add stack customization docs

* Adjust add release customization docs

* Finish nifi earthquake demo adjustments

* Start nifi water level demo adjustments

* Finish nifi water level adjustments

* Start trino iceberg adjustments

* Finish trino iceber demo adjustments

* Adjust trino taxi data demo docs

* Add installation docs

* Adjust quick start guide

* fix: nav

* docs: Remove demo docs, as they are moved to https://github.com/stackabletech/demos

* callout

* docs

* Add minor formatting

* Update broken xrefs

* Fix xrefs, remove unused section

* Update xrefs on stackablectl start page

* Update demo links

* Update fish completion instructions

* Add page aliases

---------

Co-authored-by: Sebastian Bernauer <[email protected]>

Cargo.toml

@@ -29,10 +29,12 @@ k8s-openapi = { version = "0.19", default-features = false, features = ["v1_27"]
 kube = { version = "0.85", default-features = false, features = ["client", "rustls-tls"] }
 lazy_static = "1.4"
 nu-ansi-term = "0.49"
+once_cell = "1.18"
 phf = "0.11"
 phf_codegen = "0.11"
 rand = "0.8"
-reqwest = { version = "0.11.16", default-features = false, features = ["rustls-tls"] }
+regex = "1.9"
+reqwest = { version = "0.11", default-features = false, features = ["rustls-tls"] }
 semver = "1.0"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"

docs/antora.yml

@@ -1,3 +1,7 @@
 ---
-name: home
+name: management
+title: SDP Management
 version: "nightly"
+nav:
+  - modules/cockpit/nav.adoc
+  - modules/stackablectl/nav.adoc

docs/modules/ROOT/pages/index.adoc

@@ -0,0 +1,4 @@
+= Management Tools for the Stackable Data Platform
+
+* xref:cockpit:index.adoc[]
+* xref:stackablectl:index.adoc[]

docs/modules/cockpit/nav.adoc

@@ -0,0 +1,2 @@
+* xref:index.adoc[Cockpit]
+** xref:installation.adoc[Installation]

docs/modules/cockpit/pages/index.adoc

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

docs/modules/cockpit/pages/installation.adoc

@@ -11,7 +11,8 @@ You will need:
 * Helm
 * htpasswd (from Apache HTTPD)
 
-Resource sizing depends on cluster type(s), usage and scope, but as a starting point we recommend a minimum of the following resources for this service:
+Resource sizing depends on cluster type(s), usage and scope, but as a starting point we recommend a minimum of the
+following resources for this service:
 
 * 0.2 cores (e.g. i5 or similar)
 * 256MB RAM

docs/modules/stackablectl/nav.adoc

@@ -0,0 +1,16 @@
+* xref:index.adoc[stackablectl]
+** xref:installation.adoc[Installation]
+** xref:quickstart.adoc[Quickstart]
+** xref:commands/index.adoc[Commands]
+*** xref:commands/cache.adoc[cache]
+*** xref:commands/completions.adoc[completions]
+*** xref:commands/demo.adoc[demo]
+*** xref:commands/operator.adoc[operator]
+*** xref:commands/release.adoc[release]
+*** xref:commands/stack.adoc[stack]
+*** xref:commands/stacklets.adoc[stacklets]
+** xref:customization/index.adoc[]
+*** xref:customization/add-demo.adoc[]
+*** xref:customization/add-stack.adoc[]
+*** xref:customization/add-release.adoc[]
+// *** xref:customization/working-with-feature-branches.adoc[]

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

@@ -0,0 +1,85 @@
+= stackablectl cache
+
+// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY!
+[source,console]
+----
+$ stackablectl cache
+Interact with locally cached files
+
+Usage: cache [OPTIONS] <COMMAND>
+
+Commands:
+  list   List cached files
+  clean  Clean cached files
+  help   Print this message or the help of the given subcommand(s)
+
+Options:
+  -l, --log-level <LOG_LEVEL>
+          Log level this application uses
+
+      --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.
+
+      --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/pages/commands/completions.adoc

@@ -0,0 +1,86 @@
+= stackablectl completions
+
+// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY!
+[source,console]
+----
+$ stackablectl completions
+Generate shell completions for this tool
+
+Usage: completions [OPTIONS] <COMMAND>
+
+Commands:
+  bash  Generate shell completions for Bash
+  fish  Generate shell completions for Fish
+  zsh   Generate shell completions for ZSH
+  help  Print this message or the help of the given subcommand(s)
+
+Options:
+  -l, --log-level <LOG_LEVEL>
+          Log level this application uses
+
+      --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.
+
+      --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/]
+----