added zed docs with github workflow

Signed-off-by: Kartikay <[email protected]>

Author: kartikaysaxena

.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 GenerateDocs; 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"

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
@@ -95,6 +96,7 @@ require (
 	github.com/cncf/xds/go v0.0.0-20240905190251-b4127c9b8d78 // indirect
 	github.com/containerd/cgroups/v3 v3.0.1 // indirect
 	github.com/coreos/go-systemd/v22 v22.5.0 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.4 // indirect
 	github.com/creasty/defaults v1.8.0 // indirect
 	github.com/dalzilio/rudd v1.1.1-0.20230806153452-9e08a6ea8170 // indirect
 	github.com/danieljoos/wincred v1.2.1 // indirect
@@ -200,6 +202,7 @@ require (
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/rs/cors v1.11.1 // indirect
 	github.com/rs/xid v1.6.0 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/sagikazarmark/locafero v0.4.0 // indirect
 	github.com/sagikazarmark/slog-shim v0.1.0 // indirect
 	github.com/samber/slog-common v0.18.0 // indirect

go.sum

@@ -779,6 +779,7 @@ github.com/containerd/continuity v0.4.3 h1:6HVkalIp+2u1ZLH1J/pYX2oBVXlJZvh1X1A7b
 github.com/containerd/continuity v0.4.3/go.mod h1:F6PTNCKepoxEaXLQp3wDAjygEnImnZ/7o4JzpodfroQ=
 github.com/coreos/go-systemd/v22 v22.5.0 h1:RrqgGjYQKalulkV8NGVIfkXQf6YYmOyiJKk8iXXhfZs=
 github.com/coreos/go-systemd/v22 v22.5.0/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
+github.com/cpuguy83/go-md2man/v2 v2.0.4 h1:wfIWP927BUkWJb2NmU/kNDYIBTh/ziUX91+lVfRxZq4=
 github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/creasty/defaults v1.8.0 h1:z27FJxCAa0JKt3utc0sCImAEb+spPucmKoOdLHvHYKk=
@@ -1156,6 +1157,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=
@@ -1306,6 +1309,7 @@ github.com/rs/xid v1.6.0 h1:fV591PaemRlL6JfRxGDEPl69wICngIQ3shQtzfy2gxU=
 github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
 github.com/rs/zerolog v1.33.0 h1:1cU2KZkvPxNyfgEmhHAz/1A9Bz+llsdYzklWFzgp0r8=
 github.com/rs/zerolog v1.33.0/go.mod h1:/7mN4D5sKwJLZQ2b/znpjC3/GQWY/xaDXUM0kKWRHss=
+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/ruudk/golang-pdf417 v0.0.0-20181029194003-1af4ab5afa58/go.mod h1:6lfFZQK844Gfx8o5WFuvpxWRwnSoipWe/p622j1v06w=
 github.com/ruudk/golang-pdf417 v0.0.0-20201230142125-a7e3863a1245/go.mod h1:pQAZKsJ8yyVxGRWYNEm9oFB8ieLgKFnamEyDmSA0BRk=

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"
+	"github.com/spf13/cobra/doc"
+)
+
+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 doc.GenMarkdownTree(rootCmd, targetDir)
+}