ci: Add a CI to check documentation changes

This fix introduces a new CI to check whether the command reference
documentations need to be updated.

When new commands or options are added, the
`finch gen-docs generate -p cmd/finch/` command should be run locally to
update the documentation.

However, it's easy to forget this step.

An issue has also been created that proposes to detect these differences.

- runfinch#942

Therefore, in this fix, the new CI step will generate the documentation
and compare it with the existing files.
If there are differences, the CI will fail, prompting contributors to
update the documentations.

Signed-off-by: Hayato Kiwata <[email protected]>

.github/workflows/ci-gen-docs.yaml

@@ -0,0 +1,58 @@
+# This file is used to make sure that contributors did not forget to generate the documentations for the finch commands.
+name: CI
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - 'contrib/**'
+      - '.github/CODEOWNERS'
+  pull_request:
+    branches:
+      - main
+    paths-ignore:
+      - 'contrib/**'
+      - '.github/CODEOWNERS'
+
+jobs:
+  check-documentation-changes:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@44c2b7a8a4ea60a981eaca3cf939b5f4305c123b # v4.1.5
+        with:
+          # We need to get all the git tags to make version injection work. See VERSION in Makefile for more detail.
+          fetch-depth: 0
+          persist-credentials: false
+          submodules: recursive
+      - uses: actions/setup-go@cdcb36043654635271a94b9a6d1392de5bb323a7 # v5.0.1
+        with:
+          go-version-file: go.mod
+          cache: true
+      - name: Clean up previous files
+        run: |
+          sudo rm -rf /opt/finch
+          sudo rm -rf ~/.finch
+          sudo rm -rf ./_output
+          if pgrep '^qemu-system'; then
+            sudo pkill '^qemu-system'
+          fi
+          if pgrep '^socket_vmnet'; then
+            sudo pkill '^socket_vmnet'
+          fi
+      - name: Install Rosetta 2
+        run: echo "A" | softwareupdate --install-rosetta || true
+      - run: brew install lz4 automake autoconf libtool yq
+        shell: zsh {0}
+      - name: Build project
+        run: |
+          export PATH="/opt/homebrew/opt/libtool/libexec/gnubin:$PATH"
+          make
+        shell: zsh {0}
+      - name: Generate docs
+        run: |
+          make gen-docs
+        shell: zsh {0}
+      - name: Check to generate docs
+        run: |
+          git add -N docs/cmd
+          git diff --exit-code docs/cmd

Makefile

@@ -374,6 +374,11 @@ else
 	PATH=$(GOBIN):$(PATH) go generate ./...
 endif
 
+# Generate documentations for the finch commands
+.PHONY: gen-docs
+gen-docs:
+	$(GO) run docs/gen-docs.go
+
 .PHONY: lint
 # To run golangci-lint locally: https://golangci-lint.run/usage/install/#local-installation
 lint:

docs/gen-docs.go

@@ -0,0 +1,96 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+// This program generates documentations for the finch commands.
+package main
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+)
+
+const (
+	virtualMachineRootCmd = "vm"
+)
+
+// Docs is a struct for creating documentations for the finch commands.
+type Docs struct {
+	subject string
+}
+
+// InitVM initializes the VM.
+func (d *Docs) InitVM() error {
+	return exec.Command(d.subject, virtualMachineRootCmd, "init").Run() // #nosec G204
+}
+
+// StartVM starts the VM.
+func (d *Docs) StartVM() error {
+	return exec.Command(d.subject, virtualMachineRootCmd, "start", "-f").Run() // #nosec G204
+}
+
+// StopVM stops the VM.
+func (d *Docs) StopVM() error {
+	return exec.Command(d.subject, virtualMachineRootCmd, "stop", "-f").Run() // #nosec G204
+}
+
+// RemoveVM removes the VM.
+func (d *Docs) RemoveVM() error {
+	return exec.Command(d.subject, virtualMachineRootCmd, "remove", "-f").Run() // #nosec G204
+}
+
+// CreateDocs create documentations for the finch commands.
+func (d *Docs) CreateDocs() error {
+	return exec.Command(d.subject, "gen-docs", "generate", "-p", "docs/cmd/").Run() // #nosec G204
+}
+
+// GetSubject returns the subjects for the finch command.
+func GetSubject() (string, error) {
+	wd, err := os.Getwd()
+	if err != nil {
+		return "", fmt.Errorf("failed to get the current working directory: %w", err)
+	}
+
+	subject := filepath.Join(wd, "_output", "bin", "finch")
+
+	return subject, nil
+}
+
+// NewDocs creates an object of type Docs.
+func NewDocs() (*Docs, error) {
+	d := Docs{}
+
+	subject, err := GetSubject()
+	if err != nil {
+		return &d, err
+	}
+	d.subject = subject
+
+	return &d, nil
+}
+
+func main() {
+	d, err := NewDocs()
+	if err != nil {
+		fmt.Printf("NewDocs Error: %s\n", err.Error())
+		return
+	}
+
+	err = d.StopVM()
+	if err != nil {
+		fmt.Printf("Stopping the VM Error: %s\n", err.Error())
+	}
+	err = d.RemoveVM()
+	if err != nil {
+		fmt.Printf("Removing the VM Error: %s\n", err.Error())
+	}
+	err = d.InitVM()
+	if err != nil {
+		fmt.Printf("Init the VM Error: %s\n", err.Error())
+	}
+	err = d.CreateDocs()
+	if err != nil {
+		fmt.Printf("Creating Docs Error: %s\n", err.Error())
+	}
+}