feat(actions): automatically generate help for the actions (#144)

.github/workflows/ci.yml

@@ -20,7 +20,9 @@ jobs:
           go-version-file: 'go.mod'
 
       - name: Build
-        run: go build -v ./cmd/gh-not
+        run: |
+          go generate ./...
+          go build -v ./cmd/gh-not
 
   test:
     runs-on: ubuntu-latest

.goreleaser.yaml

@@ -1,11 +1,13 @@
 # yaml-language-server: $schema=https://goreleaser.com/static/schema.json
 # vim: set ts=2 sw=2 tw=0 fo=cnqoj
+# Local testing: goreleaser --snapshot --clean
 
 version: 2
 
 before:
   hooks:
     - go mod tidy
+    - go generate ./...
 
 builds:
   - main: ./cmd/gh-not

cmd/gen-docs/main.go

@@ -0,0 +1,91 @@
+//go:build ignore
+// +build ignore
+
+package main
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+func main() {
+	parts := []string{}
+
+	err := filepath.Walk("../../internal/actions/", func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+
+		if info.IsDir() ||
+			filepath.Ext(path) != ".go" ||
+			filepath.Base(path) == "actions.go" {
+			return nil
+		}
+
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return fmt.Errorf("could not read %s: %w", path, err)
+		}
+
+		out, err := format(string(raw))
+		if err != nil {
+			return fmt.Errorf("could not get headers from %s: %w", path, err)
+		}
+
+		parts = append(parts, out)
+
+		return nil
+	})
+
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %s\n", err)
+		os.Exit(1)
+	}
+
+	if err := os.WriteFile("../../internal/cmd/actions-help.txt", []byte(strings.Join(parts, "\n\n")), 0644); err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %s\n", err)
+		os.Exit(1)
+	}
+}
+
+func format(content string) (string, error) {
+	parts := strings.Split(content, "/*")
+	if len(parts) < 2 {
+		return "", errors.New("no header found")
+	}
+
+	parts = strings.Split(parts[1], "*/")
+	if len(parts) < 2 {
+		return "", errors.New("no header end found")
+	}
+
+	header := strings.Trim(parts[0], "\n")
+	parts = strings.SplitN(header, "\n", 2)
+
+	re := regexp.MustCompile(`Package (\w+) implements an \[actions.Runner\] that (.*)\.`)
+	matches := re.FindStringSubmatch(parts[0])
+
+	if len(matches) < 3 {
+		return "", fmt.Errorf("header does not match the expected format")
+	}
+
+	outParts := []string{
+		fmt.Sprintf("%s: %s", matches[1], matches[2]),
+	}
+
+	if len(parts) == 2 {
+		tail := strings.Trim(parts[1], "\n")
+		tail = indent(tail)
+		outParts = append(outParts, tail)
+	}
+
+	return strings.Join(outParts, "\n"), nil
+}
+
+func indent(s string) string {
+	return "  " + strings.ReplaceAll(s, "\n", "\n  ")
+}

cmd/gh-not/main.go

@@ -7,6 +7,8 @@ import (
 	"github.com/nobe4/gh-not/internal/cmd"
 )
 
+//go:generate go run ../gen-docs/main.go
+
 func main() {
 	if err := cmd.Execute(); err != nil {
 		fmt.Fprintln(os.Stderr, err)

internal/actions/debug/debug.go

@@ -1,3 +1,6 @@
+/*
+Package debug implements an [actions.Runner] that prints a notification with a DEBUG prefix.
+*/
 package debug
 
 import (

internal/actions/done/done.go

@@ -1,3 +1,9 @@
+/*
+Package done implements an [actions.Runner] that marks a notification as done.
+It updates Meta.Done and marks the notification's thread as done on GitHub.
+The notification will be hidden until the thread is updated.
+Ref: https://docs.github.com/en/rest/activity/notifications?apiVersion=2022-11-28#mark-a-thread-as-done
+*/
 package done
 
 import (
@@ -11,8 +17,6 @@ import (
 	"github.com/nobe4/gh-not/internal/notifications"
 )
 
-// Runner that marks a notification as done.
-// Ref: https://docs.github.com/en/rest/activity/notifications?apiVersion=2022-11-28#mark-a-thread-as-done
 type Runner struct {
 	Client *gh.Client
 }

internal/actions/hide/hide.go

@@ -1,3 +1,7 @@
+/*
+Package hide implements an [actions.Runner] that hides a notification.
+It hides the notifications completely.
+*/
 package hide
 
 import (

internal/actions/open/open.go

@@ -1,3 +1,6 @@
+/*
+Package open implements an [actions.Runner] that opens a notification in the browser.
+*/
 package open
 
 import (

internal/actions/pass/pass.go

@@ -1,3 +1,6 @@
+/*
+Package pass implements an [actions.Runner] that does nothing.
+*/
 package pass
 
 import (

internal/actions/print/print.go

@@ -1,3 +1,6 @@
+/*
+Package print implements an [actions.Runner] that prints a notification.
+*/
 package print
 
 import (

internal/actions/read/read.go

@@ -1,3 +1,8 @@
+/*
+Package read implements an [actions.Runner] that marks a notification as read.
+It updates Unread and marks the notification's thread as read on GitHub.
+Ref: https://docs.github.com/en/rest/activity/notifications?apiVersion=2022-11-28#mark-a-thread-as-read
+*/
 package read
 
 import (
@@ -10,8 +15,6 @@ import (
 	"github.com/nobe4/gh-not/internal/notifications"
 )
 
-// Runner that marks a notification as read.
-// Ref: https://docs.github.com/en/rest/activity/notifications?apiVersion=2022-11-28#mark-a-thread-as-read
 type Runner struct {
 	Client *gh.Client
 }

internal/cmd/.gitignore

@@ -0,0 +1 @@
+actions-help.txt

internal/cmd/actions.go

@@ -1,27 +1,19 @@
 package cmd
 
-import "github.com/spf13/cobra"
+import (
+	_ "embed"
+
+	"github.com/spf13/cobra"
+)
+
+//go:embed actions-help.txt
+var longHelp string
 
 var (
 	actionsCmd = &cobra.Command{
 		Use:   "actions",
 		Short: "Show information about the actions",
-		Long: `
-'gh-not' has multiple actions that perform different actions:
-
-open: Open the notification in a web browser.
-
-hide: Mark the notification as hidden in the cache.
-      It won't show the notification again.
-
-done: Mark the notification as done in the cache and on the API.
-      It hides the notification until an update happens.
-
-read: Mark the notification as read in the cache and on the API.
-      It hides the notification until an update happens.
-
-TODO: remove debug/print/pass
-`,
+		Long:  "'gh-not' has multiple actions that perform different actions:\n\n" + longHelp,
 	}
 )