Ensure docs are up to date (#20)

* Regenerate docs

* docs: Swap out default auto-gen footer for a custom header

The custom one is a header not footer and gets rid of the embedded date. This
way we can generate in CI and verify its up to date.

Regenerate docs while we're here.

* Verify docs are up2date in CI

.github/workflows/push-pr-lint.yaml

@@ -18,9 +18,27 @@ jobs:
         version: v1.52.2
     - name: Test
       run: go test ./...
+
+  verify-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: '1.20'
+
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Generate docs
+        run: make gen-docs
+
+      - name: Verify docs are up to date
+        run: git diff | (! grep .)
+
   build:
     runs-on: ubuntu-latest
-    needs: [lint-test]
+    needs: [lint-test, verify-docs]
     steps:
       - name: Install Go
         uses: actions/setup-go@v4

cmd/generate/docs.go

@@ -18,7 +18,9 @@ var cmdGenerateDocs = &cobra.Command{
 			log.Fatal(err)
 		}
 
-		if err := cobradoc.GenMarkdownTree(cmd.Root(), "./docs"); err != nil {
+		linkHandler := func(s string) string { return s }
+		filePrepender := func(s string) string { return "[Auto generated by spf13/cobra]: <>\n\n" }
+		if err := cobradoc.GenMarkdownTreeCustom(cmd.Root(), "./docs", filePrepender, linkHandler); err != nil {
 			log.Fatal(err)
 		}
 	},

cmd/root.go

@@ -31,6 +31,8 @@ var (
 var RootCmd = &cobra.Command{
 	Use:   "mctl",
 	Short: "mctl is a CLI utility to interact with metal toolbox services",
+
+	DisableAutoGenTag: true,
 }
 
 // Execute adds all child commands to the root command and sets flags appropriately.

docs/mctl.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl
 
 mctl is a CLI utility to interact with metal toolbox services
@@ -20,5 +22,5 @@ mctl is a CLI utility to interact with metal toolbox services
 * [mctl get](mctl_get.md)	 - Get resource
 * [mctl install](mctl_install.md)	 - Install actions
 * [mctl list](mctl_list.md)	 - List resources
+* [mctl version](mctl_version.md)	 - Print mctl version
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_completion.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl completion
 
 Generate the autocompletion script for the specified shell
@@ -29,4 +31,3 @@ See each sub-command's help for details on how to use the generated script.
 * [mctl completion powershell](mctl_completion_powershell.md)	 - Generate the autocompletion script for powershell
 * [mctl completion zsh](mctl_completion_zsh.md)	 - Generate the autocompletion script for zsh
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_completion_bash.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl completion bash
 
 Generate the autocompletion script for bash
@@ -48,4 +50,3 @@ mctl completion bash
 
 * [mctl completion](mctl_completion.md)	 - Generate the autocompletion script for the specified shell
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_completion_fish.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl completion fish
 
 Generate the autocompletion script for fish
@@ -39,4 +41,3 @@ mctl completion fish [flags]
 
 * [mctl completion](mctl_completion.md)	 - Generate the autocompletion script for the specified shell
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_completion_powershell.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl completion powershell
 
 Generate the autocompletion script for powershell
@@ -36,4 +38,3 @@ mctl completion powershell [flags]
 
 * [mctl completion](mctl_completion.md)	 - Generate the autocompletion script for the specified shell
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_completion_zsh.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl completion zsh
 
 Generate the autocompletion script for zsh
@@ -50,4 +52,3 @@ mctl completion zsh [flags]
 
 * [mctl completion](mctl_completion.md)	 - Generate the autocompletion script for the specified shell
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_create.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl create
 
 Create resources
@@ -25,4 +27,3 @@ mctl create [flags]
 * [mctl create firmware](mctl_create_firmware.md)	 - Create firmware
 * [mctl create firmware-set](mctl_create_firmware-set.md)	 - Create a firmware set
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_create_firmware-set.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl create firmware-set
 
 Create a firmware set
@@ -26,4 +28,3 @@ mctl create firmware-set [flags]
 
 * [mctl create](mctl_create.md)	 - Create resources
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_create_firmware.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl create firmware
 
 Create firmware
@@ -24,4 +26,3 @@ mctl create firmware [flags]
 
 * [mctl create](mctl_create.md)	 - Create resources
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_delete.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl delete
 
 Delete resources
@@ -25,4 +27,3 @@ mctl delete [flags]
 * [mctl delete condition](mctl_delete_condition.md)	 - delete server condition
 * [mctl delete firmware-set](mctl_delete_firmware-set.md)	 - Delete a firmware set
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_delete_condition.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl delete condition
 
 delete server condition
@@ -9,9 +11,9 @@ mctl delete condition [flags]
 ### Options
 
 ```
-  -h, --help               help for condition
-      --kind string        condition kind
-      --server-id string   server UUID
+  -h, --help            help for condition
+      --kind string     condition kind
+      --server string   server UUID
 ```
 
 ### Options inherited from parent commands
@@ -25,4 +27,3 @@ mctl delete condition [flags]
 
 * [mctl delete](mctl_delete.md)	 - Delete resources
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_delete_firmware-set.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl delete firmware-set
 
 Delete a firmware set
@@ -24,4 +26,3 @@ mctl delete firmware-set [flags]
 
 * [mctl delete](mctl_delete.md)	 - Delete resources
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_edit.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl edit
 
 Edit resources
@@ -24,4 +26,3 @@ mctl edit [flags]
 * [mctl](mctl.md)	 - mctl is a CLI utility to interact with metal toolbox services
 * [mctl edit firmware-set](mctl_edit_firmware-set.md)	 - Edit a firmware set
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_edit_firmware-set.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl edit firmware-set
 
 Edit a firmware set
@@ -27,4 +29,3 @@ mctl edit firmware-set [flags]
 
 * [mctl edit](mctl_edit.md)	 - Edit resources
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_gendocs.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl gendocs
 
 Generate markdown docs for mctl CLI
@@ -23,4 +25,3 @@ mctl gendocs [flags]
 
 * [mctl](mctl.md)	 - mctl is a CLI utility to interact with metal toolbox services
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_get.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl get
 
 Get resource
@@ -27,7 +29,5 @@ mctl get [flags]
 * [mctl get component](mctl_get_component.md)	 - get server components
 * [mctl get condition](mctl_get_condition.md)	 - get server condition
 * [mctl get firmware](mctl_get_firmware.md)	 - Get information for given firmware identifier
-* [mctl get firmware](mctl_get_firmware.md)	 - Get all firmware components on a server
 * [mctl get firmware-set](mctl_get_firmware-set.md)	 - Get information for given firmware set identifier
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_get_bios-config.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl get bios-config
 
 Get bios configuration information for a server
@@ -25,4 +27,3 @@ mctl get bios-config [flags]
 
 * [mctl get](mctl_get.md)	 - Get resource
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_get_component.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl get component
 
 get server components
@@ -9,8 +11,9 @@ mctl get component [flags]
 ### Options
 
 ```
-  -h, --help               help for component
-      --server-id string   server UUID
+  -f, --firmware-only   only retrieve components with firmware
+  -h, --help            help for component
+      --server string   server UUID
 ```
 
 ### Options inherited from parent commands
@@ -25,4 +28,3 @@ mctl get component [flags]
 
 * [mctl get](mctl_get.md)	 - Get resource
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_get_condition.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl get condition
 
 get server condition
@@ -9,9 +11,9 @@ mctl get condition [flags]
 ### Options
 
 ```
-  -h, --help               help for condition
-      --kind string        condition kind
-      --server-id string   server UUID
+  -h, --help            help for condition
+      --kind string     condition kind
+      --server string   server UUID
 ```
 
 ### Options inherited from parent commands
@@ -26,4 +28,3 @@ mctl get condition [flags]
 
 * [mctl get](mctl_get.md)	 - Get resource
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_get_firmware-set.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl get firmware-set
 
 Get information for given firmware set identifier
@@ -26,4 +28,3 @@ mctl get firmware-set [flags]
 
 * [mctl get](mctl_get.md)	 - Get resource
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_get_firmware.md

@@ -1,16 +1,18 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl get firmware
 
-Get all firmware components on a server
+Get information for given firmware identifier
 
 ```
-mctl get firmware {-s | --server-id} <server uuid> [flags]
+mctl get firmware [flags]
 ```
 
 ### Options
 
 ```
-  -h, --help               help for firmware
-  -s, --server-id string   the server id to look up
+  -f, --firmware-id string   firmware UUID
+  -h, --help                 help for firmware
 ```
 
 ### Options inherited from parent commands
@@ -25,4 +27,3 @@ mctl get firmware {-s | --server-id} <server uuid> [flags]
 
 * [mctl get](mctl_get.md)	 - Get resource
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_install.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl install
 
 Install actions
@@ -23,5 +25,5 @@ mctl install [flags]
 
 * [mctl](mctl.md)	 - mctl is a CLI utility to interact with metal toolbox services
 * [mctl install firmware-set](mctl_install_firmware-set.md)	 - Install firmware set
+* [mctl install status](mctl_install_status.md)	 - check the progress of a firmware install on a server
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_install_firmware-set.md

@@ -1,3 +1,5 @@
+[Auto generated by spf13/cobra]: <>
+
 ## mctl install firmware-set
 
 Install firmware set
@@ -27,4 +29,3 @@ mctl install firmware-set [flags]
 
 * [mctl install](mctl_install.md)	 - Install actions
 
-###### Auto generated by spf13/cobra on 13-Jul-2023

docs/mctl_install_status.md

@@ -0,0 +1,28 @@
+[Auto generated by spf13/cobra]: <>
+
+## mctl install status
+
+check the progress of a firmware install on a server
+
+```
+mctl install status --server | -s <server uuid> [flags]
+```
+
+### Options
+
+```
+  -h, --help            help for status
+  -s, --server string   server id (typically a UUID)
+```
+
+### Options inherited from parent commands
+
+```
+      --config string   config file (default is $HOME/.mctl.yml)
+      --reauth          re-authenticate with oauth services
+```
+
+### SEE ALSO
+
+* [mctl install](mctl_install.md)	 - Install actions
+