diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..202f7d8 --- /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 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 "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..5373ae5 --- /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) +}