-
Notifications
You must be signed in to change notification settings - Fork 27
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added magefile to generate docs with github workflow (#456)
* added zed docs with github workflow Signed-off-by: Kartikay <[email protected]> * merging docs Signed-off-by: Kartikay <[email protected]> * gofumpt Signed-off-by: Kartikay <[email protected]> --------- Signed-off-by: Kartikay <[email protected]>
- Loading branch information
1 parent
b49f8bb
commit d5dcb8c
Showing
6 changed files
with
287 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 "[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" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| } |