Add docs for reference commands (#190)

* new cobra helper with make target; go.doc target output in docs/src/_parts/commands

* remove the cobra tagline from our docs; unhide config and status commands

* include command parts to doc index

* add go.doc to gh action so we fail fast if we dont include docs that should have been affected by a pr

---------

Co-authored-by: Nick Veitch <[email protected]>
Co-authored-by: Angelos Kolaitis <[email protected]>

.github/workflows/go.yaml

@@ -27,11 +27,15 @@ jobs:
         working-directory: src/k8s
         run: make go.fmt
 
+      - name: go doc
+        working-directory: src/k8s
+        run: make go.doc
+
       - name: check diff
         run: |
           if ! [ -z "$(git diff)" ]; then
             echo "Detected changes that have not been committed to the repository"
-            echo "Please run 'cd src/k8s && make go.fmt'"
+            echo "Please run 'cd src/k8s && make go.fmt go.doc'"
             echo "git diff:"
             git diff
             exit 1

docs/src/_parts/commands/k8s.md

@@ -0,0 +1,26 @@
+## k8s
+
+Canonical Kubernetes CLI
+
+### Options
+
+```
+  -h, --help                   help for k8s
+  -o, --output-format string   set the output format to one of plain, json or yaml (default "plain")
+  -t, --timeout duration       the max time to wait for the command to execute (default 1m30s)
+```
+
+### SEE ALSO
+
+* [k8s bootstrap](k8s_bootstrap.md)	 - Bootstrap a k8s cluster on this node
+* [k8s config](k8s_config.md)	 - Generate a kubeconfig that can be used to access the Kubernetes cluster
+* [k8s disable](k8s_disable.md)	 - Disable core cluster functionalities
+* [k8s enable](k8s_enable.md)	 - Enable core cluster functionalities
+* [k8s get](k8s_get.md)	 - get cluster configuration
+* [k8s get-join-token](k8s_get-join-token.md)	 - Create a token for a node to join the cluster
+* [k8s join-cluster](k8s_join-cluster.md)	 - Join a cluster using the provided token
+* [k8s kubectl](k8s_kubectl.md)	 - Integrated Kubernetes kubectl client
+* [k8s remove-node](k8s_remove-node.md)	 - Remove a node from the cluster
+* [k8s set](k8s_set.md)	 - Set cluster configuration
+* [k8s status](k8s_status.md)	 - Retrieve the current status of the cluster
+

docs/src/_parts/commands/k8s_bootstrap.md

@@ -0,0 +1,31 @@
+## k8s bootstrap
+
+Bootstrap a k8s cluster on this node
+
+### Synopsis
+
+Initialize the necessary folders, permissions, service arguments, certificates and start up the Kubernetes services.
+
+```
+k8s bootstrap [flags]
+```
+
+### Options
+
+```
+      --config string   path to the YAML file containing your custom cluster bootstrap configuration.
+  -h, --help            help for bootstrap
+      --interactive     interactively configure the most important cluster options
+```
+
+### Options inherited from parent commands
+
+```
+  -o, --output-format string   set the output format to one of plain, json or yaml (default "plain")
+  -t, --timeout duration       the max time to wait for the command to execute (default 1m30s)
+```
+
+### SEE ALSO
+
+* [k8s](k8s.md)	 - Canonical Kubernetes CLI
+

docs/src/_parts/commands/k8s_config.md

@@ -0,0 +1,26 @@
+## k8s config
+
+Generate a kubeconfig that can be used to access the Kubernetes cluster
+
+```
+k8s config [flags]
+```
+
+### Options
+
+```
+  -h, --help            help for config
+      --server string   custom cluster server address
+```
+
+### Options inherited from parent commands
+
+```
+  -o, --output-format string   set the output format to one of plain, json or yaml (default "plain")
+  -t, --timeout duration       the max time to wait for the command to execute (default 1m30s)
+```
+
+### SEE ALSO
+
+* [k8s](k8s.md)	 - Canonical Kubernetes CLI
+

docs/src/_parts/commands/k8s_disable.md

@@ -0,0 +1,29 @@
+## k8s disable
+
+Disable core cluster functionalities
+
+### Synopsis
+
+Disable one of network,dns,gateway,ingress,local-storage,load-balancer,metrics-server.
+
+```
+k8s disable <functionality> [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for disable
+```
+
+### Options inherited from parent commands
+
+```
+  -o, --output-format string   set the output format to one of plain, json or yaml (default "plain")
+  -t, --timeout duration       the max time to wait for the command to execute (default 1m30s)
+```
+
+### SEE ALSO
+
+* [k8s](k8s.md)	 - Canonical Kubernetes CLI
+

docs/src/_parts/commands/k8s_enable.md

@@ -0,0 +1,29 @@
+## k8s enable
+
+Enable core cluster functionalities
+
+### Synopsis
+
+Enable one of network, dns, gateway, ingress, local-storage, load-balancer, metrics-server.
+
+```
+k8s enable <functionality1> ... [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for enable
+```
+
+### Options inherited from parent commands
+
+```
+  -o, --output-format string   set the output format to one of plain, json or yaml (default "plain")
+  -t, --timeout duration       the max time to wait for the command to execute (default 1m30s)
+```
+
+### SEE ALSO
+
+* [k8s](k8s.md)	 - Canonical Kubernetes CLI
+

docs/src/_parts/commands/k8s_get-join-token.md

@@ -0,0 +1,26 @@
+## k8s get-join-token
+
+Create a token for a node to join the cluster
+
+```
+k8s get-join-token <node-name> [flags]
+```
+
+### Options
+
+```
+  -h, --help     help for get-join-token
+      --worker   generate a join token for a worker node
+```
+
+### Options inherited from parent commands
+
+```
+  -o, --output-format string   set the output format to one of plain, json or yaml (default "plain")
+  -t, --timeout duration       the max time to wait for the command to execute (default 1m30s)
+```
+
+### SEE ALSO
+
+* [k8s](k8s.md)	 - Canonical Kubernetes CLI
+

docs/src/_parts/commands/k8s_get.md

@@ -0,0 +1,29 @@
+## k8s get
+
+get cluster configuration
+
+### Synopsis
+
+Show configuration of one of network, dns, gateway, ingress, local-storage, load-balancer, metrics-server.
+
+```
+k8s get <functionality.key> [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for get
+```
+
+### Options inherited from parent commands
+
+```
+  -o, --output-format string   set the output format to one of plain, json or yaml (default "plain")
+  -t, --timeout duration       the max time to wait for the command to execute (default 1m30s)
+```
+
+### SEE ALSO
+
+* [k8s](k8s.md)	 - Canonical Kubernetes CLI
+

docs/src/_parts/commands/k8s_join-cluster.md

@@ -0,0 +1,27 @@
+## k8s join-cluster
+
+Join a cluster using the provided token
+
+```
+k8s join-cluster <join-token> [flags]
+```
+
+### Options
+
+```
+      --address string   the address (IP:Port) on which the nodes REST API should be available
+  -h, --help             help for join-cluster
+      --name string      the name of the joining node. defaults to hostname
+```
+
+### Options inherited from parent commands
+
+```
+  -o, --output-format string   set the output format to one of plain, json or yaml (default "plain")
+  -t, --timeout duration       the max time to wait for the command to execute (default 1m30s)
+```
+
+### SEE ALSO
+
+* [k8s](k8s.md)	 - Canonical Kubernetes CLI
+

docs/src/_parts/commands/k8s_kubectl.md

@@ -0,0 +1,25 @@
+## k8s kubectl
+
+Integrated Kubernetes kubectl client
+
+```
+k8s kubectl [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for kubectl
+```
+
+### Options inherited from parent commands
+
+```
+  -o, --output-format string   set the output format to one of plain, json or yaml (default "plain")
+  -t, --timeout duration       the max time to wait for the command to execute (default 1m30s)
+```
+
+### SEE ALSO
+
+* [k8s](k8s.md)	 - Canonical Kubernetes CLI
+

docs/src/_parts/commands/k8s_remove-node.md

@@ -0,0 +1,26 @@
+## k8s remove-node
+
+Remove a node from the cluster
+
+```
+k8s remove-node <node-name> [flags]
+```
+
+### Options
+
+```
+      --force   forcibly remove the cluster member
+  -h, --help    help for remove-node
+```
+
+### Options inherited from parent commands
+
+```
+  -o, --output-format string   set the output format to one of plain, json or yaml (default "plain")
+  -t, --timeout duration       the max time to wait for the command to execute (default 1m30s)
+```
+
+### SEE ALSO
+
+* [k8s](k8s.md)	 - Canonical Kubernetes CLI
+

docs/src/_parts/commands/k8s_set.md

@@ -0,0 +1,30 @@
+## k8s set
+
+Set cluster configuration
+
+### Synopsis
+
+Configure one of network, dns, gateway, ingress, local-storage, load-balancer, metrics-server.
+Use `k8s get` to explore configuration options.
+
+```
+k8s set <functionality.key=value> ... [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for set
+```
+
+### Options inherited from parent commands
+
+```
+  -o, --output-format string   set the output format to one of plain, json or yaml (default "plain")
+  -t, --timeout duration       the max time to wait for the command to execute (default 1m30s)
+```
+
+### SEE ALSO
+
+* [k8s](k8s.md)	 - Canonical Kubernetes CLI
+

docs/src/_parts/commands/k8s_status.md

@@ -0,0 +1,26 @@
+## k8s status
+
+Retrieve the current status of the cluster
+
+```
+k8s status [flags]
+```
+
+### Options
+
+```
+  -h, --help         help for status
+      --wait-ready   wait until at least one cluster node is ready
+```
+
+### Options inherited from parent commands
+
+```
+  -o, --output-format string   set the output format to one of plain, json or yaml (default "plain")
+  -t, --timeout duration       the max time to wait for the command to execute (default 1m30s)
+```
+
+### SEE ALSO
+
+* [k8s](k8s.md)	 - Canonical Kubernetes CLI
+