Skip to content

Commit

Permalink
Create CLI docs
Browse files Browse the repository at this point in the history
  • Loading branch information
chicoxyzzy committed Jul 10, 2024
1 parent d9a2892 commit ea91775
Show file tree
Hide file tree
Showing 8 changed files with 96 additions and 2 deletions.
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -34,3 +34,5 @@ goreleaser/
.netrc

.dispatch

docs/
4 changes: 4 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -39,3 +39,7 @@ push: image
update:
for ref in $$(yq -r '.deps[] | .remote + "/gen/go/" + .owner + "/" + .repository + "/protocolbuffers/go@" + .commit' proto/buf.lock); do go get $$ref; done
go mod tidy

dispatch-docs:
${GO} build -tags docs -o ${DISPATCH} .
${DISPATCH}
49 changes: 49 additions & 0 deletions cli/generate_docs.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
//go:build docs

package cli

import (
"os"
"path"
"strings"

"github.com/spf13/cobra"
"github.com/spf13/cobra/doc"
)

var isDocsBuild = true

func generateDocs(cmd *cobra.Command, filename string, title string) {
cmd.DisableAutoGenTag = true

// create docs directory
_ = os.Mkdir("./docs", 0755)

err := doc.GenMarkdownTreeCustom(cmd, "./docs",
func(_ string) string {
return `---
title: ` + title + `
---
`
},
func(name string) string {
// err := doc.GenMarkdownCustom(cmd, out, func(name string) string {
base := strings.TrimSuffix(name, path.Ext(name))
return "/cli/" + strings.ToLower(base) + "/"
})
if err != nil {
panic(err)
}

// if command has subcommands, generate markdown for each subcommand
if cmd.HasSubCommands() {
for _, c := range cmd.Commands() {
// if c.Use starts with "help", skip it
if strings.HasPrefix(c.Use, "help") {
continue
}
generateDocs(c, filename, title+" "+c.Use)
}
}
}
11 changes: 11 additions & 0 deletions cli/generate_docs_default.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
//go:build !docs

package cli

import "github.com/spf13/cobra"

var isDocsBuild = false

func generateDocs(_ *cobra.Command, _ string, _ string) {
// do nothing if the build tag "docs" is not set
}
18 changes: 17 additions & 1 deletion cli/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,19 @@ Support: [email protected]
`
)

var mainCommandText string

func createMainCommand() *cobra.Command {
if isDocsBuild {
mainCommandText = "This is the main command for Dispatch CLI. Add a subcommand to make it useful."
} else {
mainCommandText = DispatchCmdLong
}
cmd := &cobra.Command{
Version: version(),
Use: "dispatch",
Long: DispatchCmdLong,
Long: mainCommandText,
Short: "Main command for Dispatch CLI",
PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
return loadEnvFromFile(DotEnvFilePath)
},
Expand Down Expand Up @@ -50,6 +58,14 @@ func createMainCommand() *cobra.Command {
cmd.AddCommand(runCommand())
cmd.AddCommand(versionCommand())

// Generate markdown documentation
generateDocs(loginCommand(), "dispatch_login.md", "dispatch login")
generateDocs(initCommand(), "dispatch_init.md", "dispatch init")
generateDocs(switchCommand(DispatchConfigPath), "dispatch_switch.md", "dispatch switch")
generateDocs(verificationCommand(), "dispatch_verification.md", "dispatch verification")
generateDocs(runCommand(), "dispatch_run.md", "dispatch run")
generateDocs(versionCommand(), "dispatch_version.md", "dispatch version")

return cmd
}

Expand Down
10 changes: 9 additions & 1 deletion cli/run.go
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,15 @@ var (
logPrefixSeparatorStyle = lipgloss.NewStyle().Foreground(grayColor)
)

var runExampleText string

func runCommand() *cobra.Command {
if isDocsBuild {
runExampleText = "```\ndispatch run [options] -- <command>\n```"
} else {
runExampleText = " dispatch run [options] -- <command>"
}

cmd := &cobra.Command{
Use: "run",
Short: "Run a Dispatch application",
Expand All @@ -65,7 +73,7 @@ func runCommand() *cobra.Command {
The command to start the local application endpoint should be
specified after the run command and its options:
dispatch run [options] -- <command>
`+runExampleText+`
Dispatch spawns the local application endpoint and then dispatches
function calls to it continuously.
Expand Down
2 changes: 2 additions & 0 deletions go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ require (
github.com/atotto/clipboard v0.1.4 // indirect
github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
github.com/containerd/console v1.0.4-0.20230313162750-1ae8d489ac81 // indirect
github.com/cpuguy83/go-md2man/v2 v2.0.3 // indirect
github.com/davecgh/go-spew v1.1.1 // indirect
github.com/inconshreveable/mousetrap v1.1.0 // indirect
github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
Expand All @@ -33,6 +34,7 @@ require (
github.com/muesli/termenv v0.15.2 // indirect
github.com/pmezard/go-difflib v1.0.0 // indirect
github.com/rivo/uniseg v0.4.6 // indirect
github.com/russross/blackfriday/v2 v2.1.0 // indirect
github.com/spf13/pflag v1.0.5 // indirect
golang.org/x/sync v0.1.0 // indirect
golang.org/x/sys v0.19.0 // indirect
Expand Down
2 changes: 2 additions & 0 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ github.com/charmbracelet/lipgloss v0.9.1 h1:PNyd3jvaJbg4jRHKWXnCj1akQm4rh8dbEzN1
github.com/charmbracelet/lipgloss v0.9.1/go.mod h1:1mPmG4cxScwUQALAAnacHaigiiHB9Pmr+v1VEawJl6I=
github.com/containerd/console v1.0.4-0.20230313162750-1ae8d489ac81 h1:q2hJAaP1k2wIvVRd/hEHD7lacgqrCPS+k8g1MndzfWY=
github.com/containerd/console v1.0.4-0.20230313162750-1ae8d489ac81/go.mod h1:YynlIjWYF8myEu6sdkwKIvGQq+cOckRm6So2avqoYAk=
github.com/cpuguy83/go-md2man/v2 v2.0.3 h1:qMCsGGgs+MAzDFyp9LpAe1Lqy/fY/qCovCm0qnXZOBM=
github.com/cpuguy83/go-md2man/v2 v2.0.3/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
Expand Down Expand Up @@ -51,6 +52,7 @@ github.com/rivo/uniseg v0.1.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJ
github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
github.com/rivo/uniseg v0.4.6 h1:Sovz9sDSwbOz9tgUy8JpT+KgCkPYJEN/oYzlJiYTNLg=
github.com/rivo/uniseg v0.4.6/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
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/spf13/cobra v1.8.0 h1:7aJaZx1B85qltLMc546zn58BxxfZdR/W22ej9CFoEf0=
github.com/spf13/cobra v1.8.0/go.mod h1:WXLWApfZ71AjXPya3WOlMsY9yMs7YeiHhFVlvLyhcho=
Expand Down

0 comments on commit ea91775

Please sign in to comment.