Merge pull request #84 from dispatchrun/gen_docs

Create CLI docs

Author: chicoxyzzy

.gitignore

@@ -34,3 +34,5 @@ goreleaser/
 .netrc
 
 .dispatch
+
+docs/

.goreleaser.yml

@@ -1,5 +1,6 @@
 project_name: dispatch
 dist: ./goreleaser/dist
+version: 2
 
 before:
   hooks:
@@ -9,7 +10,8 @@ gomod:
   proxy: true
 
 builds:
-  - main: .
+  - id: dispatch
+    main: .
     binary: dispatch
     mod_timestamp: "{{ .CommitTimestamp }}"
 
@@ -22,6 +24,29 @@ builds:
       - linux
       - windows
 
+  - id: dispatch-docs
+    main: .
+    binary: dispatch-docs
+    mod_timestamp: "{{ .CommitTimestamp }}"
+    tags: docs
+
+    goarch:
+      - amd64
+
+    goos:
+      - linux
+
+archives:
+  - id: dispatch
+    builds: [dispatch]
+    format_overrides:
+      - goos: windows
+        format: zip
+
+  - id: dispatch-docs
+    builds: [dispatch-docs]
+    name_template: "{{ .ProjectName }}_docs_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
+
 release:
   github:
     owner: dispatchrun
@@ -34,6 +59,8 @@ changelog:
 
 brews:
   - name: dispatch
+    ids:
+      - dispatch
     url_template: "https://github.com/dispatchrun/dispatch/releases/download/{{ .Tag }}/{{ .ArtifactName }}"
 
     commit_author:

Makefile

@@ -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}

cli/generate_docs.go

@@ -0,0 +1,70 @@
+//go:build docs
+
+package cli
+
+import (
+	"bytes"
+	"os"
+	"path"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+const DispatchCmdLong = "This is the main command for Dispatch CLI. Add a subcommand to make it useful."
+
+const RunExampleText = "```\ndispatch run [options] -- <command>\n```"
+
+func generateDocs(cmd *cobra.Command, title string) {
+	cmd.DisableAutoGenTag = true
+
+	// create docs directory
+	_ = os.Mkdir("./docs", 0755)
+
+	out := new(bytes.Buffer)
+
+	err := doc.GenMarkdownCustom(cmd, out, 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)
+	}
+
+	// Define the text to be replaced and the replacement text
+	oldText := []byte("## " + title)
+	newText := []byte("---\ntitle: " + title + "\n---")
+
+	// Perform the replacement on the buffer's content
+	updatedContent := bytes.Replace(out.Bytes(), oldText, newText, 1)
+
+	// Reset the buffer and write the updated content back to it
+	out.Reset()
+	out.Write(updatedContent)
+
+	// write markdown to file
+	file, err := os.Create("./docs/" + strings.ReplaceAll(title, " ", "_") + ".md")
+	if err != nil {
+		panic(err)
+	}
+
+	_, err = file.Write(out.Bytes())
+	if err != nil {
+		panic(err)
+	}
+
+	defer file.Close()
+
+	// 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 c.Name() == "help" {
+				continue
+			}
+			generateDocs(c, title+" "+c.Name())
+		}
+	}
+}

cli/generate_docs_default.go

@@ -0,0 +1,20 @@
+//go:build !docs
+
+package cli
+
+import "github.com/spf13/cobra"
+
+const DispatchCmdLong = `Welcome to Dispatch!
+
+To get started, use the login command to authenticate with Dispatch or create an account.
+
+Documentation: https://docs.dispatch.run
+Discord: https://dispatch.run/discord
+Support: [email protected]
+`
+
+const RunExampleText = "  dispatch run [options] -- <command>"
+
+func generateDocs(_ *cobra.Command, _ string) {
+	// do nothing if the build tag "docs" is not set
+}

cli/main.go

@@ -6,22 +6,12 @@ import (
 	"github.com/spf13/cobra"
 )
 
-var (
-	DispatchCmdLong = `Welcome to Dispatch!
-
-To get started, use the login command to authenticate with Dispatch or create an account.
-
-Documentation: https://docs.dispatch.run
-Discord: https://dispatch.run/discord
-Support: [email protected]
-`
-)
-
 func createMainCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Version: version(),
 		Use:     "dispatch",
 		Long:    DispatchCmdLong,
+		Short:   "Main command for Dispatch CLI",
 		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
 			return loadEnvFromFile(DotEnvFilePath)
 		},
@@ -50,6 +40,9 @@ func createMainCommand() *cobra.Command {
 	cmd.AddCommand(runCommand())
 	cmd.AddCommand(versionCommand())
 
+	// Generate markdown documentation
+	generateDocs(cmd, "dispatch")
+
 	return cmd
 }
 

cli/run.go

@@ -65,7 +65,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.

go.mod

@@ -9,6 +9,7 @@ require (
 	github.com/charmbracelet/lipgloss v0.9.1
 	github.com/joho/godotenv v1.5.1
 	github.com/muesli/reflow v0.3.0
+	github.com/muesli/termenv v0.15.2
 	github.com/nlpodyssey/gopickle v0.3.0
 	github.com/pelletier/go-toml/v2 v2.2.0
 	github.com/spf13/cobra v1.8.0
@@ -22,6 +23,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
@@ -30,9 +32,9 @@ require (
 	github.com/mattn/go-runewidth v0.0.15 // indirect
 	github.com/muesli/ansi v0.0.0-20211018074035-2e021307bc4b // indirect
 	github.com/muesli/cancelreader v0.2.2 // indirect
-	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

go.sum

@@ -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=
@@ -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=