docs(clustertool): add more in-code documentation

clustertool/cmd/adv.go

@@ -14,6 +14,7 @@ These are all advanced commands that should generally not be needed
 var adv = &cobra.Command{
     Use:           "adv",
     Short:         "Advanced cluster maintanence commands",
+    Example:       "clustertool adv <bootstrap/health/precommit>",
     Long:          advLongHelp,
     SilenceUsage:  true,
     SilenceErrors: true,

clustertool/cmd/adv_bootstrap.go

@@ -12,10 +12,11 @@ var advBootstrapLongHelp = strings.TrimSpace(`
 `)
 
 var bootstrap = &cobra.Command{
-    Use:   "bootstrap",
+    Use:     "bootstrap",
-    Short: "bootstrap first Talos Node",
+    Short:   "bootstrap first Talos Node",
-    Long:  advBootstrapLongHelp,
+    Example: "clustertool adv bootstrap",
-    Run:   bootstrapfunc,
+    Long:    advBootstrapLongHelp,
+    Run:     bootstrapfunc,
 }
 
 func bootstrapfunc(cmd *cobra.Command, args []string) {

clustertool/cmd/adv_health.go

@@ -15,9 +15,10 @@ var advHealthLongHelp = strings.TrimSpace(`
 `)
 
 var health = &cobra.Command{
-    Use:   "health",
+    Use:     "health",
-    Short: "Check Talos Cluster Health",
+    Short:   "Check Talos Cluster Health",
-    Long:  advHealthLongHelp,
+    Example: "clustertool adv health",
+    Long:    advHealthLongHelp,
     Run: func(cmd *cobra.Command, args []string) {
         if err := sops.DecryptFiles(); err != nil {
             log.Info().Msgf("Error decrypting files: %v\n", err)

clustertool/cmd/adv_precommit.go

@@ -14,9 +14,10 @@ var advPrecommitLongHelp = strings.TrimSpace(`
 `)
 
 var precommit = &cobra.Command{
-    Use:   "precommit",
+    Use:     "precommit",
-    Short: "Runs the PreCommit encryption check",
+    Short:   "Runs the PreCommit encryption check",
-    Long:  advPrecommitLongHelp,
+    Example: "clustertool adv precommit",
+    Long:    advPrecommitLongHelp,
     Run: func(cmd *cobra.Command, args []string) {
         if err := sops.CheckFilesAndReportEncryption(true, true); err != nil {
             log.Info().Msgf("Error checking files: %v\n", err)

clustertool/cmd/adv_reset.go

@@ -14,9 +14,10 @@ var advResetLongHelp = strings.TrimSpace(`
 `)
 
 var reset = &cobra.Command{
-    Use:   "reset",
+    Use:     "reset",
-    Short: "Reset Talos Nodes and Kubernetes",
+    Short:   "Reset Talos Nodes and Kubernetes",
-    Long:  advResetLongHelp,
+    Example: "clustertool adv reset <NodeIP>",
+    Long:    advResetLongHelp,
     Run: func(cmd *cobra.Command, args []string) {
         var extraArgs []string
         node := ""

clustertool/cmd/adv_testcmd.go

@@ -10,12 +10,12 @@ import (
 )
 
 var advTestCmdlongHelp = strings.TrimSpace(`
-
+This command is mostly just for development usage and should NEVER be used by end-users.
 `)
 
 var testcmd = &cobra.Command{
     Use:   "test",
-    Short: "test run",
+    Short: "tests specific code for developer usages",
     Long:  advTestCmdlongHelp,
     Run: func(cmd *cobra.Command, args []string) {
         initfiles.LoadTalEnv(false)

clustertool/cmd/apply.go

@@ -16,9 +16,10 @@ var applyLongHelp = strings.TrimSpace(`
 `)
 
 var apply = &cobra.Command{
-    Use:   "apply",
+    Use:     "apply",
-    Short: "apply TalosConfig",
+    Short:   "apply TalosConfig",
-    Long:  applyLongHelp,
+    Example: "clustertool apply <NodeIP>",
+    Long:    applyLongHelp,
     Run: func(cmd *cobra.Command, args []string) {
         var extraArgs []string
         node := ""

clustertool/cmd/charts.go

@@ -7,12 +7,10 @@ import (
 )
 
 var chartsLongHelp = strings.TrimSpace(`
-charttool is a tool to help you build TrueCharts Charts
+charttool was a tool to help you build TrueCharts Charts.
+It has since been merged into Clustertool as "clustertool charts"
 
-Workflow:
+ Example commands
-  Create talconfig.yaml file defining your nodes information like so:
-
- Available commands
   > charttool bump 1.2.3 patch
   > charttool tagclean soemtag@somedigest
 
@@ -21,6 +19,7 @@ Workflow:
 var charts = &cobra.Command{
     Use:           "charts",
     Short:         "A tool to help with creating Talos cluster",
+    Example:       "charttool bump 1.2.3 patch",
     Long:          chartsLongHelp,
     SilenceUsage:  true,
     SilenceErrors: true,

clustertool/cmd/charts_bump.go

@@ -16,7 +16,7 @@ var bumper = &cobra.Command{
     Use:     "bump",
     Short:   "generate a bumped image version",
     Long:    chartsBumpLongHelp,
-    Example: "charttool bump <version> <kind>",
+    Example: "clustertool charts bump <version> <kind>",
     Args:    cobra.ExactArgs(2),
     Run: func(cmd *cobra.Command, args []string) {
         if err := version.Bump(args[0], args[1]); err != nil {

clustertool/cmd/charts_deps.go

@@ -17,7 +17,7 @@ var depsCmd = &cobra.Command{
     Use:     "deps",
     Short:   "Download, Update and Verify Helm dependencies",
     Long:    chartsDepsLongHelp,
-    Example: "charttool deps <chart> <chart> <chart>",
+    Example: "clustertool charts deps <chart> <chart> <chart>",
     Run: func(cmd *cobra.Command, args []string) {
         if err := deps.LoadGPGKey(); err != nil {
             log.Fatal().Err(err).Msg("failed to load gpg key")

clustertool/cmd/charts_genchangelog.go

@@ -17,7 +17,7 @@ var genChangelogCmd = &cobra.Command{
     Use:     "genchangelog",
     Short:   "Generate changelog for charts",
     Long:    chartsGenChangelogLongHelp,
-    Example: "charttool genchangelog <repo path> <template path> <charts dir>",
+    Example: "clustertool charts genchangelog <repo path> <template path> <charts dir>",
     Run: func(cmd *cobra.Command, args []string) {
         if len(args) < 3 {
             log.Fatal().Msg("Missing required arguments. Please provide the repo path, template path and charts directory.")

clustertool/cmd/charts_genchartlist.go

@@ -18,7 +18,7 @@ var genChartListCmd = &cobra.Command{
     Use:     "genchartlist",
     Short:   "Generate chart list json file",
     Long:    chartsGenChartsListLongHelp,
-    Example: "charttool genchartlist <path to charts folder>",
+    Example: "clustertool charts genchartlist <path to charts folder>",
     Run: func(cmd *cobra.Command, args []string) {
         opts := &website.ChartListOptions{
             OutputPath:  "./charts.json",

clustertool/cmd/charts_genmeta.go

@@ -17,9 +17,10 @@ var chartsGenMetaLongHelp = strings.TrimSpace(`
 `)
 
 var genMetaCmd = &cobra.Command{
-    Use:   "genmeta",
+    Use:     "genmeta",
-    Short: "Generate and update Chart.yaml metadata",
+    Short:   "Generate and update Chart.yaml metadata",
-    Long:  chartsGenMetaLongHelp,
+    Example: "clustertool charts genmeta",
+    Long:    chartsGenMetaLongHelp,
     Run: func(cmd *cobra.Command, args []string) {
         bump := ""
         if len(args) > 0 && slices.Contains([]string{"patch", "minor", "major"}, args[0]) {

clustertool/cmd/charts_tagclean.go

@@ -17,7 +17,7 @@ var tagCleaner = &cobra.Command{
     Use:     "tagcleaner",
     Short:   "Creates a clean version tag from a container digest",
     Long:    chartsTagCleanLongHelp,
-    Example: "charttool tagcleaner <tag>",
+    Example: "clustertool charts tagclean <tag>",
     Args:    cobra.ExactArgs(1),
     Run: func(cmd *cobra.Command, args []string) {
         err := image.Clean(args[0])

clustertool/cmd/checkcrypt.go

@@ -14,9 +14,10 @@ var checkcyptLongHelp = strings.TrimSpace(`
 `)
 
 var checkcrypt = &cobra.Command{
-    Use:   "checkcrypt",
+    Use:     "checkcrypt",
-    Short: "Checks if all files are encrypted correctly in accordance with .sops.yaml",
+    Short:   "Checks if all files are encrypted correctly in accordance with .sops.yaml",
-    Long:  checkcyptLongHelp,
+    Example: "clustertool checkcrypt",
+    Long:    checkcyptLongHelp,
     Run: func(cmd *cobra.Command, args []string) {
         if err := sops.CheckFilesAndReportEncryption(false, false); err != nil {
             log.Info().Msgf("Error checking files: %v\n", err)

clustertool/cmd/decrypt.go

@@ -13,9 +13,10 @@ var decryptLongHelp = strings.TrimSpace(`
 `)
 
 var decrypt = &cobra.Command{
-    Use:   "decrypt",
+    Use:     "decrypt",
-    Short: "Decrypt all high-risk data using sops",
+    Short:   "Decrypt all high-risk data using sops",
-    Long:  decryptLongHelp,
+    Example: "clustertool decrypt",
+    Long:    decryptLongHelp,
     Run: func(cmd *cobra.Command, args []string) {
         if err := sops.DecryptFiles(); err != nil {
             log.Info().Msgf("Error decrypting files: %v\n", err)

clustertool/cmd/encrypt.go

@@ -13,9 +13,10 @@ var encryptLongHelp = strings.TrimSpace(`
 `)
 
 var encrypt = &cobra.Command{
-    Use:   "encrypt",
+    Use:     "encrypt",
-    Short: "Encrypt all high-risk data using sops",
+    Short:   "Encrypt all high-risk data using sops",
-    Long:  encryptLongHelp,
+    Example: "clustertool encrypt",
+    Long:    encryptLongHelp,
     Run: func(cmd *cobra.Command, args []string) {
         if err := sops.EncryptAllFiles(); err != nil {
             log.Info().Msgf("Error encrypting files: %v\n", err)

clustertool/cmd/fluxbootstrap.go

@@ -18,9 +18,10 @@ var fluxBootstrapLongHelp = strings.TrimSpace(`
 `)
 
 var fluxbootstrap = &cobra.Command{
-    Use:   "fluxbootstrap",
+    Use:     "fluxbootstrap",
-    Short: "Manually bootstrap fluxcd on existing cluster",
+    Short:   "Manually bootstrap fluxcd on existing cluster",
-    Long:  fluxBootstrapLongHelp,
+    Example: "clustertool fluxbootstrap",
+    Long:    fluxBootstrapLongHelp,
     Run: func(cmd *cobra.Command, args []string) {
         ctx := context.Background()
 

clustertool/cmd/helmrelease.go

@@ -7,13 +7,14 @@ import (
 )
 
 var helmreleaseHelp = strings.TrimSpace(`
-A toolkit to load helm-release files onto a cluster without flux
+A toolkit to load helm-release files onto a cluster without flux.
-
+originally created to make it easier to install/upgrade/edit flux-based clusterresources without flux
 `)
 
 var helmrelease = &cobra.Command{
     Use:           "helmrelease",
     Short:         "A toolkit to load helm-release files onto a cluster without flux",
+    Example:       "clustertool helmrelease <install/upgrade>",
     Long:          advLongHelp,
     SilenceUsage:  true,
     SilenceErrors: true,

clustertool/cmd/helmrelease_install.go

@@ -14,9 +14,10 @@ var hrInstalLongHelp = strings.TrimSpace(`
 `)
 
 var hrinstall = &cobra.Command{
-    Use:   "install",
+    Use:     "install",
-    Short: "install a helm-release file without flux, helm-release file needs to be called helm-release.yaml",
+    Short:   "install a helm-release file without flux, helm-release file needs to be called helm-release.yaml",
-    Long:  hrInstalLongHelp,
+    Example: "clustertool helmrelease install",
+    Long:    hrInstalLongHelp,
     Run: func(cmd *cobra.Command, args []string) {
         initfiles.LoadTalEnv(false)
 

clustertool/cmd/helmrelease_upgrade.go

@@ -14,9 +14,10 @@ var hrUpgradeLongHelp = strings.TrimSpace(`
 `)
 
 var hrupgrade = &cobra.Command{
-    Use:   "upgrade",
+    Use:     "upgrade",
-    Short: "run helm-upgrade using a helm-release file without flux",
+    Short:   "run helm-upgrade using a helm-release file without flux",
-    Long:  hrUpgradeLongHelp,
+    Example: "clustertool helmrelease upgrade",
+    Long:    hrUpgradeLongHelp,
     Run: func(cmd *cobra.Command, args []string) {
         initfiles.LoadTalEnv(false)
 

clustertool/cmd/info.go

@@ -8,6 +8,15 @@ import (
 )
 
 var infoLongHelp = strings.TrimSpace(`
+clustertool is a tool to help you easily deploy and maintain a Talos Kubernetes Cluster.
+
+
+Workflow:
+  Create talconfig.yaml file defining your nodes information like so:
+
+ Available commands
+  > clustertool init
+  > clustertool genconfig
 
 `)
 

clustertool/cmd/init.go

@@ -16,7 +16,6 @@ Afterwards you can edit talconfig.yaml and clusterenv.yaml to reflect your perso
 
 When done, please run clustertool genconfig to generate all configarion based on your personal settings
 
-Powered by TalHelper (https://budimanjojo.github.io/talhelper/)
 
 `)
 

clustertool/cmd/root.go

@@ -3,7 +3,6 @@ package cmd
 import (
     "os"
     "path/filepath"
-    "strings"
 
     "github.com/rs/zerolog/log"
     "github.com/spf13/cobra"
@@ -12,25 +11,10 @@ import (
 
 var thisversion string
 
-var rootLongHelp = strings.TrimSpace(`
-clustertool is a tool to help you easily deploy and maintain a Talos Kubernetes Cluster.
-
-
-Workflow:
-  Create talconfig.yaml file defining your nodes information like so:
-
- Available commands
-  > clustertool init
-  > clustertool genconfig
-
-  Powered by TalHelper (https://budimanjojo.github.io/talhelper/)
-
-`)
-
 var RootCmd = &cobra.Command{
     Use:           "clustertool",
     Short:         "A tool to help with creating Talos cluster",
-    Long:          rootLongHelp,
+    Long:          infoLongHelp,
     SilenceUsage:  true,
     SilenceErrors: true,
     Version:       thisversion,

clustertool/cmd/scale.go

@@ -7,13 +7,16 @@ import (
 )
 
 var scaleLongHelp = strings.TrimSpace(`
-These are all advanced commands that should generally not be needed
+These are all commands that are exclusively intended to migrate away from TrueNAS SCALE Kubernetes Apps to a normal kubernets cluster.
+
+They will all, at a later date, be removed.
 
 `)
 
 var scaleCmd = &cobra.Command{
     Use:           "scale",
     Short:         "Commands for handling TrueNAS SCALE",
+    Example:       "clustertool scale export",
     Long:          advLongHelp,
     SilenceUsage:  true,
     SilenceErrors: true,

clustertool/cmd/scale_export.go

@@ -12,9 +12,10 @@ var scaleExportLongHelp = strings.TrimSpace(`
 `)
 
 var scaleexport = &cobra.Command{
-    Use:   "export",
+    Use:     "export",
-    Short: "Export SCALE Apps to file",
+    Short:   "Export SCALE Apps to file",
-    Long:  scaleExportLongHelp,
+    Example: "clustertool scale export",
+    Long:    scaleExportLongHelp,
     Run: func(cmd *cobra.Command, args []string) {
         scale.ExportApps()
     },

clustertool/cmd/scale_migrate.go

@@ -13,9 +13,10 @@ var scaleMigrateLongHelp = strings.TrimSpace(`
 `)
 
 var scalemigrate = &cobra.Command{
-    Use:   "migrate",
+    Use:     "migrate",
-    Short: "Migrate exported SCALE Apps to the Talos Cluster",
+    Short:   "Migrate exported SCALE Apps to the Talos Cluster",
-    Long:  scaleMigrateLongHelp,
+    Example: "clustertool scale migrate",
+    Long:    scaleMigrateLongHelp,
     Run: func(cmd *cobra.Command, args []string) {
         err := scale.ProcessJSONFiles("./truenas_exports")
         if err != nil {

clustertool/cmd/upgrade.go

@@ -15,9 +15,10 @@ var upgradeLongHelp = strings.TrimSpace(`
 `)
 
 var upgrade = &cobra.Command{
-    Use:   "upgrade",
+    Use:     "upgrade",
-    Short: "Upgrade Talos Nodes and Kubernetes",
+    Short:   "Upgrade Talos Nodes and Kubernetes",
-    Long:  upgradeLongHelp,
+    Example: "clustertool upgrade <NodeIP>",
+    Long:    upgradeLongHelp,
     Run: func(cmd *cobra.Command, args []string) {
         var extraArgs []string
         node := ""