Added magefile to generate docs with github workflow

.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/zed"
+
+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 "actions@github.com"
+
+      - 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"

go.mod

@@ -20,6 +20,7 @@ require (
 	github.com/hamba/avro/v2 v2.27.0
 	github.com/jzelinskie/cobrautil/v2 v2.0.0-20240819150235-f7fe73942d0f
 	github.com/jzelinskie/stringz v0.0.3
+	github.com/magefile/mage v1.15.0
 	github.com/mattn/go-isatty v0.0.20
 	github.com/mitchellh/go-homedir v1.1.0
 	github.com/muesli/termenv v0.15.2

go.sum

@@ -1156,6 +1156,8 @@ github.com/lucasb-eyer/go-colorful v1.2.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i
 github.com/lyft/protoc-gen-star v0.6.0/go.mod h1:TGAoBVkt8w7MPG72TrKIu85MIdXwDuzJYeZuUPFPNwA=
 github.com/lyft/protoc-gen-star v0.6.1/go.mod h1:TGAoBVkt8w7MPG72TrKIu85MIdXwDuzJYeZuUPFPNwA=
 github.com/lyft/protoc-gen-star/v2 v2.0.1/go.mod h1:RcCdONR2ScXaYnQC5tUzxzlpA3WVYF7/opLeUgcQs/o=
+github.com/magefile/mage v1.15.0 h1:BvGheCMAsG3bWUDbZ8AyXXpCNwU9u5CB6sM+HNb9HYg=
+github.com/magefile/mage v1.15.0/go.mod h1:z5UZb/iS3GoOSn0JgWuiw7dxlurVYTu+/jHXqQg881A=
 github.com/magiconair/properties v1.8.7 h1:IeQXZAiQcpL9mgcAe1Nu6cX9LLw6ExEHKjN0VQdvPDY=
 github.com/magiconair/properties v1.8.7/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
 github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0=

internal/cmd/cmd.go

@@ -42,9 +42,8 @@ func init() {
 	log.Logger = l
 }
 
-func Run() {
-	zl := cobrazerolog.New(cobrazerolog.WithPreRunLevel(zerolog.DebugLevel))
-
+// This function is utilised to generate docs for zed
+func InitialiseRootCmd(zl *cobrazerolog.Builder) *cobra.Command {
 	rootCmd := &cobra.Command{
 		Use:   "zed",
 		Short: "SpiceDB client, by AuthZed",
@@ -113,6 +112,14 @@ func Run() {
 	schemaCmd := commands.RegisterSchemaCmd(rootCmd)
 	registerAdditionalSchemaCmds(schemaCmd)
 
+	return rootCmd
+}
+
+func Run() {
+	zl := cobrazerolog.New(cobrazerolog.WithPreRunLevel(zerolog.DebugLevel))
+
+	rootCmd := InitialiseRootCmd(zl)
+
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
 

magefiles/magefile.go

@@ -0,0 +1,34 @@
+//go:build mage
+// +build mage
+
+package main
+
+import (
+	"os"
+
+	"github.com/authzed/zed/internal/cmd"
+	"github.com/jzelinskie/cobrautil/v2/cobrazerolog"
+	"github.com/magefile/mage/mg"
+)
+
+type Gen mg.Namespace
+
+// All Run all generators in parallel
+func (g Gen) All() error {
+	mg.Deps(g.Docs)
+	return nil
+}
+
+// Generate markdown files for zed
+func (Gen) Docs() error {
+	targetDir := "../docs"
+
+	err := os.MkdirAll("../docs", os.ModePerm)
+	if err != nil {
+		return err
+	}
+
+	rootCmd := cmd.InitialiseRootCmd(cobrazerolog.New())
+
+	return GenCustomMarkdownTree(rootCmd, targetDir)
+}

magefiles/util.go

@@ -0,0 +1,155 @@
+//go:build mage
+// +build mage
+
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+type byName []*cobra.Command
+
+type CommandContent struct {
+	Name    string
+	Content string
+}
+
+func (s byName) Len() int           { return len(s) }
+func (s byName) Swap(i, j int)      { s[i], s[j] = s[j], s[i] }
+func (s byName) Less(i, j int) bool { return s[i].Name() < s[j].Name() }
+
+func GenCustomMarkdownTree(cmd *cobra.Command, dir string) error {
+	basename := strings.ReplaceAll(cmd.CommandPath(), " ", "_") + ".md"
+	filename := filepath.Join(dir, basename)
+
+	f, err := os.Create(filename)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	return genMarkdownTreeCustom(cmd, f)
+}
+
+func genMarkdownTreeCustom(cmd *cobra.Command, f *os.File) error {
+	var commandContents []CommandContent
+
+	collectCommandContent(cmd, &commandContents)
+
+	// for sorting commands and their content
+	sort.Slice(commandContents, func(i, j int) bool {
+		return commandContents[i].Name < commandContents[j].Name
+	})
+
+	for _, cc := range commandContents {
+		_, err := f.WriteString(cc.Content)
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func collectCommandContent(cmd *cobra.Command, commandContents *[]CommandContent) {
+	buf := new(bytes.Buffer)
+	name := cmd.CommandPath()
+
+	buf.WriteString("## " + name + "\n\n")
+	buf.WriteString(cmd.Short + "\n\n")
+	if len(cmd.Long) > 0 {
+		buf.WriteString("### Synopsis\n\n")
+		buf.WriteString(cmd.Long + "\n\n")
+	}
+
+	if cmd.Runnable() {
+		buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.UseLine()))
+	}
+
+	if len(cmd.Example) > 0 {
+		buf.WriteString("### Examples\n\n")
+		buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.Example))
+	}
+
+	if err := printOptions(buf, cmd); err != nil {
+		fmt.Println("Error printing options:", err)
+	}
+
+	if hasSeeAlso(cmd) {
+		buf.WriteString("### SEE ALSO\n\n")
+		if cmd.HasParent() {
+			parent := cmd.Parent()
+			pname := parent.CommandPath()
+			pname = strings.ReplaceAll(strings.ReplaceAll(pname, "_", "-"), " ", "-")
+
+			buf.WriteString(fmt.Sprintf("* [%s](#%s)\t - %s\n", pname, pname, parent.Short))
+		}
+
+		children := cmd.Commands()
+		sort.Sort(byName(children))
+
+		for _, child := range children {
+			if !child.IsAvailableCommand() || child.IsAdditionalHelpTopicCommand() {
+				continue
+			}
+			cname := name + " " + child.Name()
+			link := strings.ReplaceAll(strings.ReplaceAll(cname, "_", "-"), " ", "-")
+			buf.WriteString(fmt.Sprintf("* [%s](#%s)\t - %s\n", cname, link, child.Short))
+		}
+		buf.WriteString("\n\n")
+	}
+
+	*commandContents = append(*commandContents, CommandContent{
+		Name:    name,
+		Content: buf.String(),
+	})
+
+	for _, c := range cmd.Commands() {
+		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
+			continue
+		}
+		collectCommandContent(c, commandContents)
+	}
+}
+
+func hasSeeAlso(cmd *cobra.Command) bool {
+	if cmd.HasParent() {
+		return true
+	}
+	for _, c := range cmd.Commands() {
+		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
+			continue
+		}
+		return true
+	}
+	return false
+}
+
+func printOptions(buf *bytes.Buffer, cmd *cobra.Command) error {
+	flags := cmd.NonInheritedFlags()
+	flags.SetOutput(buf)
+
+	if flags.HasAvailableFlags() {
+		buf.WriteString("### Options\n\n```\n")
+		flags.PrintDefaults()
+		buf.WriteString("```\n\n")
+	}
+
+	parentFlags := cmd.InheritedFlags()
+	parentFlags.SetOutput(buf)
+
+	if parentFlags.HasAvailableFlags() {
+		buf.WriteString("### Options Inherited From Parent Flags\n\n```\n")
+		parentFlags.PrintDefaults()
+		buf.WriteString("```\n\n")
+	}
+
+	return nil
+}