From b5e88dab09e2f0a7645ed8949058ba98f50513a5 Mon Sep 17 00:00:00 2001 From: Kartikay Date: Fri, 17 Jan 2025 18:35:00 +0530 Subject: [PATCH 1/3] added zed docs with github workflow Signed-off-by: Kartikay --- .github/workflows/docs.yaml | 85 +++++++++++++++++++++++++++++++++++++ go.mod | 3 ++ go.sum | 4 ++ internal/cmd/cmd.go | 13 ++++-- magefiles/magefile.go | 34 +++++++++++++++ 5 files changed, 136 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/docs.yaml create mode 100644 magefiles/magefile.go diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..4118275 --- /dev/null +++ b/.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" diff --git a/go.mod b/go.mod index 0770fa6..59d4b0e 100644 --- a/go.mod +++ b/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 diff --git a/go.sum b/go.sum index e800305..901a61f 100644 --- a/go.sum +++ b/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= diff --git a/internal/cmd/cmd.go b/internal/cmd/cmd.go index 554a8cd..0f0dbe9 100644 --- a/internal/cmd/cmd.go +++ b/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() diff --git a/magefiles/magefile.go b/magefiles/magefile.go new file mode 100644 index 0000000..54fb170 --- /dev/null +++ b/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) +} From deede2e60bb2b66e82e07e24e264508790b1ffdd Mon Sep 17 00:00:00 2001 From: Kartikay Date: Tue, 28 Jan 2025 05:27:17 +0530 Subject: [PATCH 2/3] merging docs Signed-off-by: Kartikay --- go.mod | 2 - go.sum | 2 - magefiles/magefile.go | 7 +- magefiles/util.go | 156 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 159 insertions(+), 8 deletions(-) create mode 100644 magefiles/util.go diff --git a/go.mod b/go.mod index 59d4b0e..17b5235 100644 --- a/go.mod +++ b/go.mod @@ -96,7 +96,6 @@ 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 @@ -202,7 +201,6 @@ 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 diff --git a/go.sum b/go.sum index 901a61f..e7ba5c3 100644 --- a/go.sum +++ b/go.sum @@ -779,7 +779,6 @@ 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= @@ -1309,7 +1308,6 @@ 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= diff --git a/magefiles/magefile.go b/magefiles/magefile.go index 54fb170..e974333 100644 --- a/magefiles/magefile.go +++ b/magefiles/magefile.go @@ -4,12 +4,10 @@ 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" + "os" ) type Gen mg.Namespace @@ -30,5 +28,6 @@ func (Gen) Docs() error { } rootCmd := cmd.InitialiseRootCmd(cobrazerolog.New()) - return doc.GenMarkdownTree(rootCmd, targetDir) + + return GenCustomMarkdownTree(rootCmd, targetDir) } diff --git a/magefiles/util.go b/magefiles/util.go new file mode 100644 index 0000000..528f28f --- /dev/null +++ b/magefiles/util.go @@ -0,0 +1,156 @@ +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 flags.HasAvailableFlags() { + buf.WriteString("### Options Inherited From Parent Flags\n\n```\n") + flags.PrintDefaults() + buf.WriteString("```\n\n") + } + + return nil + +} From 8a20dd119ad94c5fc6076b2e1e45a35f95e0e9ac Mon Sep 17 00:00:00 2001 From: Kartikay Date: Tue, 28 Jan 2025 20:12:28 +0530 Subject: [PATCH 3/3] gofumpt Signed-off-by: Kartikay --- magefiles/magefile.go | 3 ++- magefiles/util.go | 11 +++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/magefiles/magefile.go b/magefiles/magefile.go index e974333..5b5c959 100644 --- a/magefiles/magefile.go +++ b/magefiles/magefile.go @@ -4,10 +4,11 @@ package main import ( + "os" + "github.com/authzed/zed/internal/cmd" "github.com/jzelinskie/cobrautil/v2/cobrazerolog" "github.com/magefile/mage/mg" - "os" ) type Gen mg.Namespace diff --git a/magefiles/util.go b/magefiles/util.go index 528f28f..4ab19ec 100644 --- a/magefiles/util.go +++ b/magefiles/util.go @@ -1,3 +1,6 @@ +//go:build mage +// +build mage + package main import ( @@ -23,7 +26,6 @@ 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) @@ -34,7 +36,6 @@ func GenCustomMarkdownTree(cmd *cobra.Command, dir string) error { defer f.Close() return genMarkdownTreeCustom(cmd, f) - } func genMarkdownTreeCustom(cmd *cobra.Command, f *os.File) error { @@ -132,7 +133,6 @@ func hasSeeAlso(cmd *cobra.Command) bool { } func printOptions(buf *bytes.Buffer, cmd *cobra.Command) error { - flags := cmd.NonInheritedFlags() flags.SetOutput(buf) @@ -145,12 +145,11 @@ func printOptions(buf *bytes.Buffer, cmd *cobra.Command) error { parentFlags := cmd.InheritedFlags() parentFlags.SetOutput(buf) - if flags.HasAvailableFlags() { + if parentFlags.HasAvailableFlags() { buf.WriteString("### Options Inherited From Parent Flags\n\n```\n") - flags.PrintDefaults() + parentFlags.PrintDefaults() buf.WriteString("```\n\n") } return nil - }