docs: added magefile target to generate docs

.github/workflows/docs.yaml

@@ -0,0 +1,85 @@
+---
+name: "Sync Generated Docs"
+on:  # yamllint disable-line rule:truthy
+  push:
+    branches:
+      - "main"
+
+env:
+  DOCS_REPO: "authzed/docs"
+  DOCS_BRANCH: "main"
+  GENERATED_DOCS_DIR: "docs"
+  TARGET_DOCS_DIR: "pages/spicedb/docs"
+
+permissions:
+  contents: "write"
+  pull-requests: "write"
+
+jobs:
+  generate-and-sync-docs:
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: "Checkout source repository"
+        uses: "actions/checkout@v3"
+        with:
+          fetch-depth: 1
+
+      - name: "Set up Go"
+        uses: "actions/setup-go@v4"
+        with:
+          go-version: 1.20
+
+      - name: "Generate documentation"
+        run: |
+          cd magefiles
+          if ! mage gen:docs; then
+            echo "Documentation generation failed"
+            exit 1
+          fi
+
+      - name: "Clone docs repository"
+        run: |
+          git clone --depth 1 --branch $DOCS_BRANCH https://github.com/$DOCS_REPO.git docs-repo || {
+            echo "Failed to clone docs repository"
+            exit 1
+          }
+
+      - name: "Compare generated docs with target docs"
+        id: "compare"
+        run: |
+          rsync -r --delete $GENERATED_DOCS_DIR/ docs-repo/$TARGET_DOCS_DIR
+          cd docs-repo
+          if git diff --exit-code; then
+            echo "No changes detected in docs."
+            echo "changes_detected=false" >> $GITHUB_ENV
+          else
+            echo "Changes detected in docs."
+            echo "changes_detected=true" >> $GITHUB_ENV
+          fi
+
+      - name: "Configure Git"
+        if: "env.changes_detected == true"
+        run: |
+          cd docs-repo
+          git config user.name "GitHub Actions"
+          git config user.email "[email protected]"
+
+      - name: "Commit and push changes if any"
+        if: "env.changes_detected == true"
+        run: |
+          cd docs-repo
+          git add $TARGET_DOCS_DIR
+          git commit -m "Update generated docs"
+          git push origin $DOCS_BRANCH
+
+      - name: "Create a pull request"
+        if: "env.changes_detected == true"
+        uses: "peter-evans/create-pull-request@v5"
+        with:
+          token: "${{ secrets.GITHUB_TOKEN }}"
+          commit-message: "Update generated docs"
+          branch: "update-generated-docs"
+          title: "Sync generated docs"
+          body: |
+            This PR updates the generated documentation files in `$TARGET_DOCS_DIR` with the latest version from the main repository.
+          base: "$DOCS_BRANCH"

cmd/spicedb/main.go

@@ -2,28 +2,21 @@ package main
 
 import (
 	"errors"
-	"fmt"
 	"os"
 
-	mcobra "github.com/muesli/mango-cobra"
-	"github.com/muesli/roff"
 	"github.com/rs/zerolog"
 	"github.com/sercand/kuberesolver/v5"
-	"github.com/spf13/cobra"
 	"google.golang.org/grpc/balancer"
 
 	_ "google.golang.org/grpc/xds"
 
 	log "github.com/authzed/spicedb/internal/logging"
-	"github.com/authzed/spicedb/pkg/cmd"
+	cmd "github.com/authzed/spicedb/pkg/cmd"
 	cmdutil "github.com/authzed/spicedb/pkg/cmd/server"
-	"github.com/authzed/spicedb/pkg/cmd/testserver"
 	_ "github.com/authzed/spicedb/pkg/runtime"
 	"github.com/authzed/spicedb/pkg/spiceerrors"
 )
 
-var errParsing = errors.New("parsing error")
-
 func main() {
 	// Set up root logger
 	// This will typically be overwritten by the logging setup for a given command.
@@ -36,88 +29,10 @@ func main() {
 	balancer.Register(cmdutil.ConsistentHashringBuilder)
 
 	// Create a root command
-	rootCmd := cmd.NewRootCommand("spicedb")
-	rootCmd.SetFlagErrorFunc(func(cmd *cobra.Command, err error) error {
-		cmd.Println(err)
-		cmd.Println(cmd.UsageString())
-		return errParsing
-	})
-	if err := cmd.RegisterRootFlags(rootCmd); err != nil {
-		log.Fatal().Err(err).Msg("failed to register root flags")
-	}
-
-	// Add a version command
-	versionCmd := cmd.NewVersionCommand(rootCmd.Use)
-	cmd.RegisterVersionFlags(versionCmd)
-	rootCmd.AddCommand(versionCmd)
-
-	// Add datastore commands
-	datastoreCmd, err := cmd.NewDatastoreCommand(rootCmd.Use)
-	if err != nil {
-		log.Fatal().Err(err).Msg("failed to register datastore command")
-	}
-
-	cmd.RegisterDatastoreRootFlags(datastoreCmd)
-	rootCmd.AddCommand(datastoreCmd)
-
-	// Add deprecated head command
-	headCmd := cmd.NewHeadCommand(rootCmd.Use)
-	cmd.RegisterHeadFlags(headCmd)
-	headCmd.Hidden = true
-	headCmd.RunE = cmd.DeprecatedRunE(headCmd.RunE, "spicedb datastore head")
-	rootCmd.AddCommand(headCmd)
-
-	// Add deprecated migrate command
-	migrateCmd := cmd.NewMigrateCommand(rootCmd.Use)
-	migrateCmd.Hidden = true
-	migrateCmd.RunE = cmd.DeprecatedRunE(migrateCmd.RunE, "spicedb datastore migrate")
-	cmd.RegisterMigrateFlags(migrateCmd)
-	rootCmd.AddCommand(migrateCmd)
-
-	// Add server commands
-	serverConfig := cmdutil.NewConfigWithOptionsAndDefaults()
-	serveCmd := cmd.NewServeCommand(rootCmd.Use, serverConfig)
-	if err := cmd.RegisterServeFlags(serveCmd, serverConfig); err != nil {
-		log.Fatal().Err(err).Msg("failed to register server flags")
-	}
-	rootCmd.AddCommand(serveCmd)
-
-	devtoolsCmd := cmd.NewDevtoolsCommand(rootCmd.Use)
-	cmd.RegisterDevtoolsFlags(devtoolsCmd)
-	rootCmd.AddCommand(devtoolsCmd)
-
-	lspConfig := new(cmd.LSPConfig)
-	lspCmd := cmd.NewLSPCommand(rootCmd.Use, lspConfig)
-	if err := cmd.RegisterLSPFlags(lspCmd, lspConfig); err != nil {
-		log.Fatal().Err(err).Msg("failed to register lsp flags")
-	}
-	rootCmd.AddCommand(lspCmd)
-
-	var testServerConfig testserver.Config
-	testingCmd := cmd.NewTestingCommand(rootCmd.Use, &testServerConfig)
-	cmd.RegisterTestingFlags(testingCmd, &testServerConfig)
-	rootCmd.AddCommand(testingCmd)
-
-	rootCmd.AddCommand(&cobra.Command{
-		Use:                   "man",
-		Short:                 "Generate the SpiceDB manpage",
-		SilenceUsage:          true,
-		DisableFlagsInUseLine: true,
-		Hidden:                true,
-		Args:                  cobra.NoArgs,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			manPage, err := mcobra.NewManPage(1, cmd.Root())
-			if err != nil {
-				return err
-			}
-
-			_, err = fmt.Fprint(os.Stdout, manPage.Build(roff.NewDocument()))
-			return err
-		},
-	})
+	rootCmd := cmd.InitialiseRootCmd()
 
 	if err := rootCmd.Execute(); err != nil {
-		if !errors.Is(err, errParsing) {
+		if !errors.Is(err, cmd.ErrParsing) {
 			log.Err(err).Msg("terminated with errors")
 		}
 		var termErr spiceerrors.TerminationError

magefiles/gen.go

@@ -5,19 +5,39 @@ package main
 import (
 	"fmt"
 	"os"
+	"regexp"
 
+	cmd "github.com/authzed/spicedb/pkg/cmd"
 	"github.com/magefile/mage/mg"
 	"github.com/magefile/mage/sh"
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
 )
 
 type Gen mg.Namespace
 
 // All Run all generators in parallel
 func (g Gen) All() error {
-	mg.Deps(g.Go, g.Proto)
+	mg.Deps(g.Go, g.Proto, g.Docs)
 	return nil
 }
 
+// Generate markdown files for SpiceDB
+func (Gen) Docs() error {
+	targetDir := "../docs"
+
+	err := os.MkdirAll("../docs", os.ModePerm)
+	if err != nil {
+		return err
+	}
+
+	rootCmd := cmd.InitialiseRootCmd()
+
+	// Clean up ANSI codes which embeds colorized output before generating docs
+	cleanCommand(rootCmd)
+	return doc.GenMarkdownTree(rootCmd, targetDir)
+}
+
 // Go Run go codegen
 func (Gen) Go() error {
 	fmt.Println("generating go")
@@ -49,3 +69,19 @@ func (Gen) Completions() error {
 	}
 	return nil
 }
+
+// stripANSI removes ANSI escape codes from a string.
+func stripANSI(s string) string {
+	re := regexp.MustCompile(`\x1b\[[0-9;]*[mK]`)
+	return re.ReplaceAllString(s, "")
+}
+
+func cleanCommand(cmd *cobra.Command) {
+	cmd.Long = stripANSI(cmd.Long)
+	cmd.Short = stripANSI(cmd.Short)
+	cmd.Example = stripANSI(cmd.Example)
+
+	for _, subCmd := range cmd.Commands() {
+		cleanCommand(subCmd)
+	}
+}