diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 00000000..4118275c --- /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 e1cd9179..8749d843 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 diff --git a/go.sum b/go.sum index 09e3ffa6..07c2c7f0 100644 --- a/go.sum +++ b/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= diff --git a/internal/cmd/cmd.go b/internal/cmd/cmd.go index 4786928b..5ce1f6a5 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", @@ -114,6 +113,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 00000000..5b5c959c --- /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" +) + +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) +} diff --git a/magefiles/util.go b/magefiles/util.go new file mode 100644 index 00000000..4ab19ecb --- /dev/null +++ b/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 +}