feat: enforce generation of docs for commands

.github/workflows/tidy_up_repository.sh

@@ -15,6 +15,7 @@ commands=(
     "bazel run @go_sdk//:bin/go -- mod tidy"
     "bazel run //:update_go_deps"
     "bazel run //:gazelle"
+    "bazel run //docs:command_list_update"
 )
 
 for cmd in "${commands[@]}"; do

cmd/aspect/root/root.go

@@ -101,7 +101,7 @@ func NewRootCmd(
 	})
 	cmd.AddCommand(&cobra.Command{
 		Use:   "tags",
-		Short: "Conventions for tags which are special",
+		Short: "Conventions for tags which are special.",
 		Long:  topics.MustAssetString("tags.md"),
 	})
 

cmd/docgen/BUILD.bazel

@@ -9,6 +9,7 @@ go_library(
         "//cmd/aspect/root",
         "//pkg/ioutils",
         "//pkg/plugin/system",
+        "@com_github_spf13_cobra//:cobra",
         "@com_github_spf13_cobra//doc",
     ],
 )

cmd/docgen/main.go

@@ -1,9 +1,10 @@
 package main
 
 import (
+	"fmt"
 	"log"
-	"os"
 
+	"github.com/spf13/cobra"
 	"github.com/spf13/cobra/doc"
 
 	"aspect.build/cli/cmd/aspect/root"
@@ -12,18 +13,62 @@ import (
 )
 
 func main() {
-	if len(os.Args) != 2 {
-		log.Fatal("Usage: cmd/docgen /path/to/outdir")
-	}
+	cmd := &cobra.Command{Use: "docgen"}
 
 	pluginSystem := system.NewPluginSystem()
 	if err := pluginSystem.Configure(ioutils.DefaultStreams); err != nil {
 		log.Fatal(err)
 	}
 	defer pluginSystem.TearDown()
 
-	err := doc.GenMarkdownTree(root.NewDefaultRootCmd(pluginSystem), os.Args[1])
-	if err != nil {
+	aspectRootCmd := root.NewDefaultRootCmd(pluginSystem)
+
+	cmd.AddCommand(NewBzlCommandListCmd(aspectRootCmd))
+	cmd.AddCommand(NewGenMarkdownCmd(aspectRootCmd))
+
+	if err := cmd.Execute(); err != nil {
 		log.Fatal(err)
 	}
 }
+
+func NewBzlCommandListCmd(aspectRootCmd *cobra.Command) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "bzl-command-list",
+		Short: "Prints a .bzl file with the top-level list of commands of the aspect CLI.",
+		Long: "This command is used to produce the .bzl file with the list of top-level commands" +
+			"used to automatically generate markdown documentation for this repository.",
+		RunE: func(_ *cobra.Command, _ []string) (exitErr error) {
+			fmt.Println(`"""Generated file - do NOT edit!`)
+			fmt.Println("This module contains the list of top-level commands from the aspect CLI.")
+			fmt.Println(`"""`)
+			fmt.Println("COMMAND_LIST = [")
+			cmds := aspectRootCmd.Commands()
+			for _, cmd := range cmds {
+				if cmd.IsAvailableCommand() {
+					fmt.Printf("    %q,\n", cmd.Use)
+				}
+			}
+			fmt.Println("]")
+			return nil
+		},
+	}
+	return cmd
+}
+
+func NewGenMarkdownCmd(aspectRootCmd *cobra.Command) *cobra.Command {
+	var outputDir string
+
+	cmd := &cobra.Command{
+		Use:   "gen-markdown",
+		Short: "Generates the markdown documentation.",
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return doc.GenMarkdownTree(aspectRootCmd, outputDir)
+		},
+	}
+
+	outputDirFlag := "output-dir"
+	cmd.PersistentFlags().StringVar(&outputDir, outputDirFlag, "", "The path to the output directory.")
+	cmd.MarkPersistentFlagRequired(outputDirFlag)
+
+	return cmd
+}

docs/BUILD.bazel

@@ -1,23 +1,40 @@
 load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
 load("@bazel_skylib//rules:write_file.bzl", "write_file")
+load(":command_list.bzl", "COMMAND_LIST")
 
-# This list must be updated when we add a new command
-# buildifier: keep sorted
-_DOCS = [
-    "aspect.md",
-    "aspect_build.md",
-    "aspect_clean.md",
-    "aspect_docs.md",
-    "aspect_info.md",
-    "aspect_run.md",
-    "aspect_test.md",
-    "aspect_version.md",
+_DOCS = ["aspect.md"] + [
+    "aspect_{}.md".format(cmd)
+    for cmd in COMMAND_LIST
 ]
 
+genrule(
+    name = "command_list_bzl",
+    outs = ["command_list.bzl"],
+    cmd = "$(execpath //cmd/docgen) bzl-command-list > $@",
+    tools = ["//cmd/docgen"],
+)
+
+write_file(
+    name = "gen_command_list_update",
+    out = "command_list_update.sh",
+    content = [
+        "#!/usr/bin/env bash",
+        "set -o errexit -o nounset -o pipefail",
+        "cd $BUILD_WORKSPACE_DIRECTORY",
+        "cp -fv bazel-bin/docs/command_list.bzl docs/command_list.bzl",
+    ],
+)
+
+sh_binary(
+    name = "command_list_update",
+    srcs = ["command_list_update.sh"],
+    data = [":command_list_bzl"],
+)
+
 genrule(
     name = "docgen",
     outs = ["gen/" + d for d in _DOCS],
-    cmd = "$(execpath //cmd/docgen) $(@D)/gen",
+    cmd = "$(execpath //cmd/docgen) gen-markdown --output-dir $(@D)/gen",
     tools = ["//cmd/docgen"],
 )
 
@@ -39,6 +56,7 @@ write_file(
     out = "update.sh",
     content = [
         "#!/usr/bin/env bash",
+        "set -o errexit -o nounset -o pipefail",
         "cd $BUILD_WORKSPACE_DIRECTORY",
     ] + [
         "cp -fv bazel-bin/docs/gen/{0} docs/{0}".format(file)

docs/command_list.bzl

@@ -0,0 +1,12 @@
+"""Generated file - do NOT edit!
+This module contains the list of top-level commands from the aspect CLI.
+"""
+COMMAND_LIST = [
+    "build",
+    "clean",
+    "docs",
+    "info",
+    "run",
+    "test",
+    "version",
+]