Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create CLI docs #84

Merged
merged 5 commits into from
Jul 16, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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/
29 changes: 28 additions & 1 deletion .goreleaser.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
project_name: dispatch
dist: ./goreleaser/dist
version: 2

before:
hooks:
Expand All @@ -9,7 +10,8 @@ gomod:
proxy: true

builds:
- main: .
- id: dispatch
main: .
binary: dispatch
mod_timestamp: "{{ .CommitTimestamp }}"

Expand All @@ -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
Expand All @@ -34,6 +59,8 @@ changelog:

brews:
- name: dispatch
ids:
- dispatch
url_template: "https://github.com/dispatchrun/dispatch/releases/download/{{ .Tag }}/{{ .ArtifactName }}"

commit_author:
Expand Down
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}
70 changes: 70 additions & 0 deletions cli/generate_docs.go
Original file line number Diff line number Diff line change
@@ -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())
}
}
}
20 changes: 20 additions & 0 deletions cli/generate_docs_default.go
Original file line number Diff line number Diff line change
@@ -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
}
15 changes: 4 additions & 11 deletions cli/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
},
Expand Down Expand Up @@ -50,6 +40,9 @@ func createMainCommand() *cobra.Command {
cmd.AddCommand(runCommand())
cmd.AddCommand(versionCommand())

// Generate markdown documentation
generateDocs(cmd, "dispatch")

return cmd
}

Expand Down
2 changes: 1 addition & 1 deletion cli/run.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 3 additions & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
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
Loading