feat: generate markdown docs, for some future GitHub pages site

cmd/aspect/BUILD.bazel

diff --git a/cmd/aspect/BUILD.bazel b/cmd/aspect/BUILD.bazel
index cfb7f47..07b802d 100644
--- a/cmd/aspect/BUILD.bazel
+++ b/cmd/aspect/BUILD.bazel
@@ -2,21 +2,12 @@
 
 go_library(
     name = "aspect_lib",
-    srcs = [
-        "main.go",
-        "root.go",
-    ],
+    srcs = ["main.go"],
     importpath = "aspect.build/cli/cmd/aspect",
-    visibility = ["//visibility:private"],
+    visibility = ["//cmd:__subpackages__"],
     deps = [
-        "//cmd/aspect/version",
-        "//docs/help/topics",
-        "//pkg/ioutils",
-        "@com_github_fatih_color//:color",
-        "@com_github_mattn_go_isatty//:go-isatty",
-        "@com_github_mitchellh_go_homedir//:go-homedir",
+        "//cmd/aspect/root",
         "@com_github_spf13_cobra//:cobra",
-        "@com_github_spf13_viper//:viper",
     ],
 )
 

cmd/aspect/main.go

diff --git a/cmd/aspect/main.go b/cmd/aspect/main.go
index 8ee6f4d..12b014a 100644
--- a/cmd/aspect/main.go
+++ b/cmd/aspect/main.go
@@ -6,6 +6,7 @@
 
 package main
 
+import "aspect.build/cli/cmd/aspect/root"
 import "github.com/spf13/cobra"
 
 func main() {
@@ -20,6 +21,6 @@
 	//     ask the user if they want to install for all users of the workspace, if so
 	//         - tools/bazel file and put our bootstrap code in there
 	//
-	cmd := NewDefaultRootCmd()
+	cmd := root.NewDefaultRootCmd()
 	cobra.CheckErr(cmd.Execute())
 }

cmd/aspect/root/BUILD.bazel

diff --git a/cmd/aspect/root/BUILD.bazel b/cmd/aspect/root/BUILD.bazel
new file mode 100644
index 0000000..762e55d
--- /dev/null
+++ b/cmd/aspect/root/BUILD.bazel
@@ -0,0 +1,18 @@
+load("@io_bazel_rules_go//go:def.bzl", "go_library")
+
+go_library(
+    name = "root",
+    srcs = ["root.go"],
+    importpath = "aspect.build/cli/cmd/aspect/root",
+    visibility = ["//visibility:public"],
+    deps = [
+        "//cmd/aspect/version",
+        "//docs/help/topics",
+        "//pkg/ioutils",
+        "@com_github_fatih_color//:color",
+        "@com_github_mattn_go_isatty//:go-isatty",
+        "@com_github_mitchellh_go_homedir//:go-homedir",
+        "@com_github_spf13_cobra//:cobra",
+        "@com_github_spf13_viper//:viper",
+    ],
+)

cmd/aspect/root/root.go

diff --git a/cmd/aspect/root.go b/cmd/aspect/root/root.go
similarity index 99%
rename from cmd/aspect/root.go
rename to cmd/aspect/root/root.go
index eff635d..9478de7 100644
--- a/cmd/aspect/root.go
+++ b/cmd/aspect/root/root.go
@@ -4,7 +4,7 @@
 Not licensed for re-use.
 */
 
-package main
+package root
 
 import (
 	"os"

cmd/aspect/version/version.go

diff --git a/cmd/aspect/version/version.go b/cmd/aspect/version/version.go
index 21553c9..6d35ef1 100644
--- a/cmd/aspect/version/version.go
+++ b/cmd/aspect/version/version.go
@@ -31,7 +31,7 @@
 		RunE:  v.Run,
 	}
 
-	cmd.PersistentFlags().BoolVarP(&v.GNUFormat, "gnu_format", "", false, "format help following GNU convention")
+	cmd.PersistentFlags().BoolVarP(&v.GNUFormat, "gnu_format", "", false, "format space-separated following GNU convention")
 
 	return cmd
 }

cmd/docgen/BUILD.bazel

diff --git a/cmd/docgen/BUILD.bazel b/cmd/docgen/BUILD.bazel
new file mode 100644
index 0000000..385d481
--- /dev/null
+++ b/cmd/docgen/BUILD.bazel
@@ -0,0 +1,18 @@
+load("@io_bazel_rules_go//go:def.bzl", "go_binary", "go_library")
+
+go_library(
+    name = "docgen_lib",
+    srcs = ["main.go"],
+    importpath = "aspect.build/cli/cmd/docgen",
+    visibility = ["//visibility:private"],
+    deps = [
+        "//cmd/aspect/root",
+        "@com_github_spf13_cobra//doc",
+    ],
+)
+
+go_binary(
+    name = "docgen",
+    embed = [":docgen_lib"],
+    visibility = ["//visibility:public"],
+)

cmd/docgen/README.md

diff --git a/cmd/docgen/README.md b/cmd/docgen/README.md
new file mode 100644
index 0000000..1951d50
--- /dev/null
+++ b/cmd/docgen/README.md
@@ -0,0 +1,8 @@
+# Generating docs
+
+Run `bazel run //cmd/docgen /tmp | less`
+
+Note that piping the command to less is required, so that it's not interactive.
+Otherwise we'll turn on coloring and put ANSI escape codes in our markdown.
+
+The github.com/aspect-dev/docs repo will do the work of publishing the outputs of this docgen step.

cmd/docgen/main.go

diff --git a/cmd/docgen/main.go b/cmd/docgen/main.go
new file mode 100644
index 0000000..a7cb5ab
--- /dev/null
+++ b/cmd/docgen/main.go
@@ -0,0 +1,21 @@
+package main
+
+import (
+	"log"
+	"os"
+
+	"aspect.build/cli/cmd/aspect/root"
+	"github.com/spf13/cobra/doc"
+)
+
+func main() {
+	if len(os.Args) != 2 {
+		log.Fatal("Usage: cmd/docgen /path/to/outdir")
+		os.Exit(1)
+	}
+
+	err := doc.GenMarkdownTree(root.NewDefaultRootCmd(), os.Args[1])
+	if err != nil {
+		log.Fatal(err)
+	}
+}