docs: add hidden docs command to generate markdown cli reference

tests: fail if the docs need to be regenerated

Signed-off-by: Adphi <philippe.adrien.nousse@gmail.com>

Makefile

@@ -28,6 +28,8 @@ GORELEASER_URL := https://github.com/goreleaser/goreleaser/releases/download/$(G
 BIN := $(PWD)/bin
 export PATH := $(BIN):$(PATH)
 
+CLI_REFERENCE_PATH := docs/reference
+
 bin:
 	@mkdir -p $(BIN)
 	@curl -sL $(GORELEASER_URL) | tar -C $(BIN) -xz goreleaser
@@ -63,6 +65,8 @@ docker-run:
 tests:
 	@go generate ./...
 	@go list ./...| xargs go test -exec sudo -count=1 -timeout 20m -v
+	@$(MAKE) docs
+	@git diff --quiet || (echo "Please regenerate the documentation with 'make docs'"; exit 1)
 
 check-fmt:
 	@[ "$(gofmt -l $(find . -name '*.go') 2>&1)" = "" ]
@@ -101,3 +105,7 @@ examples: build-dev
 	  done
 	@echo "Building examples/full/Dockerfile"
 	@./d2vm build -o examples/build/full.qcow2 --build-arg=USER=adphi --build-arg=PASSWORD=adphi examples/full
+
+docs: .build
+	@rm -rf $(CLI_REFERENCE_PATH)
+	@./d2vm docs $(CLI_REFERENCE_PATH)

cmd/d2vm/docs.go

@@ -0,0 +1,43 @@
+// Copyright 2022 Linka Cloud  All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"os"
+
+	"github.com/sirupsen/logrus"
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+var docsCmd = &cobra.Command{
+	Use:    "docs",
+	Short:  "Generate documentation",
+	Args:   cobra.ExactArgs(1),
+	Hidden: true,
+	Run: func(cmd *cobra.Command, args []string) {
+		if err := os.MkdirAll(args[0], 0755); err != nil {
+			logrus.Fatal(err)
+		}
+		cmd.Root().DisableAutoGenTag = true
+		if err := doc.GenMarkdownTree(cmd.Root(), args[0]); err != nil {
+			logrus.Fatal(err)
+		}
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(docsCmd)
+}

cmd/d2vm/run.go

@@ -23,7 +23,7 @@ import (
 var (
 	runCmd = &cobra.Command{
 		Use:   "run",
-		Short: "run the converted virtual machine",
+		Short: "Run the virtual machine image",
 	}
 )
 

cmd/d2vm/run/hetzner.go

@@ -51,9 +51,10 @@ var (
 	hetznerRemove     = false
 
 	HetznerCmd = &cobra.Command{
-		Use:  "hetzner [options] image-path",
-		Args: cobra.ExactArgs(1),
-		Run:  Hetzner,
+		Use:   "hetzner [options] image-path",
+		Short: "Run the virtual machine image on Hetzner Cloud",
+		Args:  cobra.ExactArgs(1),
+		Run:   Hetzner,
 	}
 )
 

cmd/d2vm/run/qemu.go

@@ -41,9 +41,10 @@ var (
 	usbEnabled   bool
 
 	QemuCmd = &cobra.Command{
-		Use:  "qemu [options] [image-path]",
-		Args: cobra.ExactArgs(1),
-		Run:  Qemu,
+		Use:   "qemu [options] [image-path]",
+		Short: "Run the virtual machine image with qemu",
+		Args:  cobra.ExactArgs(1),
+		Run:   Qemu,
 	}
 )
 

cmd/d2vm/run/vbox.go

@@ -20,9 +20,10 @@ import (
 
 var (
 	VboxCmd = &cobra.Command{
-		Use:  "vbox [options] image-path",
-		Args: cobra.ExactArgs(1),
-		Run:  Vbox,
+		Use:   "vbox [options] image-path",
+		Short: "Run the virtual machine image with Virtualbox",
+		Args:  cobra.ExactArgs(1),
+		Run:   Vbox,
 	}
 
 	vboxmanageFlag string

docs/reference/d2vm.md

@@ -0,0 +1,19 @@
+## d2vm
+
+
+
+### Options
+
+```
+  -h, --help      help for d2vm
+  -v, --verbose   Enable Verbose output
+```
+
+### SEE ALSO
+
+* [d2vm build](d2vm_build.md)	 - Build a vm image from Dockerfile
+* [d2vm completion](d2vm_completion.md)	 - Generate the autocompletion script for the specified shell
+* [d2vm convert](d2vm_convert.md)	 - Convert Docker image to vm image
+* [d2vm run](d2vm_run.md)	 - Run the virtual machine image
+* [d2vm version](d2vm_version.md)	 - 
+

docs/reference/d2vm_build.md

@@ -0,0 +1,32 @@
+## d2vm build
+
+Build a vm image from Dockerfile
+
+```
+d2vm build [context directory] [flags]
+```
+
+### Options
+
+```
+      --append-to-cmdline string   Extra kernel cmdline arguments to append to the generated one
+      --build-arg stringArray      Set build-time variables
+  -f, --file string                Name of the Dockerfile
+      --force                      Override output image
+  -h, --help                       help for build
+      --network-manager string     Network manager to use for the image: none, netplan, ifupdown
+  -o, --output string              The output image, the extension determine the image format, raw will be used if none. Supported formats: qcow2 qed raw vdi vhd vmdk (default "disk0.qcow2")
+  -p, --password string            Root user password (default "root")
+  -s, --size string                The output image size (default "10G")
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose   Enable Verbose output
+```
+
+### SEE ALSO
+
+* [d2vm](d2vm.md)	 - 
+

docs/reference/d2vm_completion.md

@@ -0,0 +1,30 @@
+## d2vm completion
+
+Generate the autocompletion script for the specified shell
+
+### Synopsis
+
+Generate the autocompletion script for d2vm for the specified shell.
+See each sub-command's help for details on how to use the generated script.
+
+
+### Options
+
+```
+  -h, --help   help for completion
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose   Enable Verbose output
+```
+
+### SEE ALSO
+
+* [d2vm](d2vm.md)	 - 
+* [d2vm completion bash](d2vm_completion_bash.md)	 - Generate the autocompletion script for bash
+* [d2vm completion fish](d2vm_completion_fish.md)	 - Generate the autocompletion script for fish
+* [d2vm completion powershell](d2vm_completion_powershell.md)	 - Generate the autocompletion script for powershell
+* [d2vm completion zsh](d2vm_completion_zsh.md)	 - Generate the autocompletion script for zsh
+

docs/reference/d2vm_completion_bash.md

@@ -0,0 +1,49 @@
+## d2vm completion bash
+
+Generate the autocompletion script for bash
+
+### Synopsis
+
+Generate the autocompletion script for the bash shell.
+
+This script depends on the 'bash-completion' package.
+If it is not installed already, you can install it via your OS's package manager.
+
+To load completions in your current shell session:
+
+	source <(d2vm completion bash)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	d2vm completion bash > /etc/bash_completion.d/d2vm
+
+#### macOS:
+
+	d2vm completion bash > /usr/local/etc/bash_completion.d/d2vm
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+d2vm completion bash
+```
+
+### Options
+
+```
+  -h, --help              help for bash
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose   Enable Verbose output
+```
+
+### SEE ALSO
+
+* [d2vm completion](d2vm_completion.md)	 - Generate the autocompletion script for the specified shell
+

docs/reference/d2vm_completion_fish.md

@@ -0,0 +1,40 @@
+## d2vm completion fish
+
+Generate the autocompletion script for fish
+
+### Synopsis
+
+Generate the autocompletion script for the fish shell.
+
+To load completions in your current shell session:
+
+	d2vm completion fish | source
+
+To load completions for every new session, execute once:
+
+	d2vm completion fish > ~/.config/fish/completions/d2vm.fish
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+d2vm completion fish [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for fish
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose   Enable Verbose output
+```
+
+### SEE ALSO
+
+* [d2vm completion](d2vm_completion.md)	 - Generate the autocompletion script for the specified shell
+

docs/reference/d2vm_completion_powershell.md

@@ -0,0 +1,37 @@
+## d2vm completion powershell
+
+Generate the autocompletion script for powershell
+
+### Synopsis
+
+Generate the autocompletion script for powershell.
+
+To load completions in your current shell session:
+
+	d2vm completion powershell | Out-String | Invoke-Expression
+
+To load completions for every new session, add the output of the above command
+to your powershell profile.
+
+
+```
+d2vm completion powershell [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for powershell
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose   Enable Verbose output
+```
+
+### SEE ALSO
+
+* [d2vm completion](d2vm_completion.md)	 - Generate the autocompletion script for the specified shell
+

docs/reference/d2vm_completion_zsh.md

@@ -0,0 +1,47 @@
+## d2vm completion zsh
+
+Generate the autocompletion script for zsh
+
+### Synopsis
+
+Generate the autocompletion script for the zsh shell.
+
+If shell completion is not already enabled in your environment you will need
+to enable it.  You can execute the following once:
+
+	echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	d2vm completion zsh > "${fpath[1]}/_d2vm"
+
+#### macOS:
+
+	d2vm completion zsh > /usr/local/share/zsh/site-functions/_d2vm
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+d2vm completion zsh [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for zsh
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose   Enable Verbose output
+```
+
+### SEE ALSO
+
+* [d2vm completion](d2vm_completion.md)	 - Generate the autocompletion script for the specified shell
+

docs/reference/d2vm_convert.md

@@ -0,0 +1,31 @@
+## d2vm convert
+
+Convert Docker image to vm image
+
+```
+d2vm convert [docker image] [flags]
+```
+
+### Options
+
+```
+      --append-to-cmdline string   Extra kernel cmdline arguments to append to the generated one
+  -f, --force                      Override output qcow2 image
+  -h, --help                       help for convert
+      --network-manager string     Network manager to use for the image: none, netplan, ifupdown
+  -o, --output string              The output image, the extension determine the image format, raw will be used if none. Supported formats: qcow2 qed raw vdi vhd vmdk (default "disk0.qcow2")
+  -p, --password string            The Root user password (default "root")
+      --pull                       Always pull docker image
+  -s, --size string                The output image size (default "10G")
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose   Enable Verbose output
+```
+
+### SEE ALSO
+
+* [d2vm](d2vm.md)	 - 
+

docs/reference/d2vm_run.md

@@ -0,0 +1,23 @@
+## d2vm run
+
+Run the virtual machine image
+
+### Options
+
+```
+  -h, --help   help for run
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose   Enable Verbose output
+```
+
+### SEE ALSO
+
+* [d2vm](d2vm.md)	 - 
+* [d2vm run hetzner](d2vm_run_hetzner.md)	 - Run the virtual machine image on Hetzner Cloud
+* [d2vm run qemu](d2vm_run_qemu.md)	 - Run the virtual machine image with qemu
+* [d2vm run vbox](d2vm_run_vbox.md)	 - Run the virtual machine image with Virtualbox
+

docs/reference/d2vm_run_hetzner.md

@@ -0,0 +1,29 @@
+## d2vm run hetzner
+
+Run the virtual machine image on Hetzner Cloud
+
+```
+d2vm run hetzner [options] image-path [flags]
+```
+
+### Options
+
+```
+  -h, --help             help for hetzner
+  -n, --name string      d2vm server name (default "d2vm")
+      --rm               remove server when done
+  -i, --ssh-key string   d2vm image identity key
+  -t, --token string     Hetzner Cloud API token [$HETZNER_TOKEN]
+  -u, --user string      d2vm image ssh user (default "root")
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose   Enable Verbose output
+```
+
+### SEE ALSO
+
+* [d2vm run](d2vm_run.md)	 - Run the virtual machine image
+

docs/reference/d2vm_run_qemu.md

@@ -0,0 +1,37 @@
+## d2vm run qemu
+
+Run the virtual machine image with qemu
+
+```
+d2vm run qemu [options] [image-path] [flags]
+```
+
+### Options
+
+```
+      --accel string            Choose acceleration mode. Use 'tcg' to disable it. (default "hvf:tcg")
+      --arch string             Type of architecture to use, e.g. x86_64, aarch64, s390x (default "x86_64")
+      --cpus uint               Number of CPUs (default 1)
+      --data string             String of metadata to pass to VM; error to specify both -data and -data-file
+      --detached                Set qemu container to run in the background
+      --device multiple-flag    Add USB host device(s). Format driver[,prop=value][,...] -- add device, like -device on the qemu command line. (default A multiple flag is a type of flag that can be repeated any number of times)
+      --disk disk               Disk config, may be repeated. [file=]path[,size=1G][,format=qcow2] (default [])
+      --gui                     Set qemu to use video output instead of stdio
+  -h, --help                    help for qemu
+      --mem uint                Amount of memory in MB (default 1024)
+      --networking string       Networking mode. Valid options are 'default', 'user', 'bridge[,name]', tap[,name] and 'none'. 'user' uses QEMUs userspace networking. 'bridge' connects to a preexisting bridge. 'tap' uses a prexisting tap device. 'none' disables networking.` (default "user")
+      --publish multiple-flag   Publish a vm's port(s) to the host (default []) (default A multiple flag is a type of flag that can be repeated any number of times)
+      --qemu string             Path to the qemu binary (otherwise look in $PATH)
+      --usb                     Enable USB controller
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose   Enable Verbose output
+```
+
+### SEE ALSO
+
+* [d2vm run](d2vm_run.md)	 - Run the virtual machine image
+

docs/reference/d2vm_run_vbox.md

@@ -0,0 +1,31 @@
+## d2vm run vbox
+
+Run the virtual machine image with Virtualbox
+
+```
+d2vm run vbox [options] image-path [flags]
+```
+
+### Options
+
+```
+      --cpus uint               Number of CPUs (default 1)
+      --disk disk               Disk config, may be repeated. [file=]path[,size=1G][,format=raw] (default [])
+      --gui                     Show the VM GUI
+  -h, --help                    help for vbox
+      --mem uint                Amount of memory in MB (default 1024)
+      --name string             Name of the Virtualbox VM
+      --networking vbnetworks   Network config, may be repeated. [type=](null|nat|bridged|intnet|hostonly|generic|natnetwork[<devicename>])[,[bridge|host]adapter=<interface>] (default [])
+      --vboxmanage string       VBoxManage binary to use (default "VBoxManage")
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose   Enable Verbose output
+```
+
+### SEE ALSO
+
+* [d2vm run](d2vm_run.md)	 - Run the virtual machine image
+

docs/reference/d2vm_version.md

@@ -0,0 +1,24 @@
+## d2vm version
+
+
+
+```
+d2vm version [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for version
+```
+
+### Options inherited from parent commands
+
+```
+  -v, --verbose   Enable Verbose output
+```
+
+### SEE ALSO
+
+* [d2vm](d2vm.md)	 - 
+

go.mod

@@ -25,6 +25,7 @@ require (
 	github.com/cespare/xxhash/v2 v2.1.2 // indirect
 	github.com/containerd/containerd v1.5.8 // indirect
 	github.com/containerd/stargz-snapshotter/estargz v0.10.1 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.1 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/docker/cli v20.10.12+incompatible // indirect
 	github.com/docker/distribution v2.7.1+incompatible // indirect
@@ -48,6 +49,7 @@ require (
 	github.com/prometheus/client_model v0.2.0 // indirect
 	github.com/prometheus/common v0.26.0 // indirect
 	github.com/prometheus/procfs v0.6.0 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/vbatts/tar-split v0.11.2 // indirect
 	go.uber.org/atomic v1.7.0 // indirect
@@ -58,5 +60,6 @@ require (
 	google.golang.org/genproto v0.0.0-20211208223120-3a66f561d7aa // indirect
 	google.golang.org/grpc v1.43.0 // indirect
 	google.golang.org/protobuf v1.27.1 // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
 	gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b // indirect
 )

go.sum

@@ -258,6 +258,7 @@ github.com/coreos/pkg v0.0.0-20160727233714-3ac0863d7acf/go.mod h1:E3G3o1h8I7cfc
 github.com/coreos/pkg v0.0.0-20180928190104-399ea9e2e55f/go.mod h1:E3G3o1h8I7cfcXa63jLwjI0eiQQMgzzUDFVpN/nH/eA=
 github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
 github.com/cpuguy83/go-md2man/v2 v2.0.0/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
+github.com/cpuguy83/go-md2man/v2 v2.0.1 h1:r/myEWzV9lfsM1tFLgDyu0atFtJ1fXn261LKYj/3DxU=
 github.com/cpuguy83/go-md2man/v2 v2.0.1/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/creack/pty v1.1.7/go.mod h1:lj5s0c3V2DBrqTV7llrYr5NG6My20zk30Fl46Y7DoTY=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
@@ -705,6 +706,7 @@ github.com/rogpeppe/fastuuid v0.0.0-20150106093220-6724a57986af/go.mod h1:XWv6So
 github.com/rogpeppe/fastuuid v1.2.0/go.mod h1:jVj6XXZzXRy/MSR5jhDC/2q6DgLz+nrA6LYCDYWNEvQ=
 github.com/rogpeppe/go-internal v1.3.0/go.mod h1:M8bDsm7K2OlrFYOpmOWEs/qY81heoFRclV5y23lUDJ4=
 github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/ryanuber/columnize v0.0.0-20160712163229-9b3edd62028f/go.mod h1:sm1tb6uqfes/u+d4ooFouqFdy9/2g9QGwK3SQygK0Ts=
 github.com/safchain/ethtool v0.0.0-20190326074333-42ed695e3de8/go.mod h1:Z0q5wiBQGYcxhMZ6gUqHn6pYNLypFAvaL3UvgZLR0U4=
@@ -1338,6 +1340,7 @@ gopkg.in/yaml.v2 v2.2.4/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.5/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
 gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b h1:h8qDotaEPuJATrMmW04NCwg7v22aHH28wwpauUhK9Oo=