🔨 Add tooling for generating documentation

Author: bitwizeshift

go.mod

@@ -0,0 +1,8 @@
+module github.com/bitwizeshift/actions-github
+
+go 1.21.1
+
+require (
+	github.com/iancoleman/strcase v0.3.0
+	gopkg.in/yaml.v3 v3.0.1
+)

go.sum

@@ -0,0 +1,5 @@
+github.com/iancoleman/strcase v0.3.0 h1:nTXanmYxhfFAMjZL34Ov6gkzEsSJZ5DbhxWjvSASxEI=
+github.com/iancoleman/strcase v0.3.0/go.mod h1:iwCmte+B7n89clKwxIoIXy/HfoL7AsD47ZCWhYzw7ho=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

tools/generate-docs/README.md.template

@@ -0,0 +1,22 @@
+# `actions-github`
+
+This repository provides easy-to-use [composite actions] for managing a Github
+repository in [Github workflows]. All actions wrap the [octokit api] via
+[`actions/github-script`][github-script].
+
+## Available Actions
+
+Below are the list of available actions, with links to documentation:
+
+{{.ActionTable}}
+## License
+
+Except where otherwise specified, this project is dual-licensed under both the
+[Apache-2] and [MIT] licenses.
+
+[Apache-2]: https://opensource.org/license/apache-2-0/
+[MIT]: http://opensource.org/licenses/MIT/
+[composite actions]: https://docs.github.com/en/actions/creating-actions/creating-a-composite-action
+[octokit api]: https://octokit.github.io/rest.js/v20
+[Github workflows]: https://docs.github.com/en/actions/using-workflows
+[github-script]: https://github.com/actions/github-script

tools/generate-docs/main.go

@@ -0,0 +1,298 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"html/template"
+	"io"
+	"io/fs"
+	"os"
+	"path"
+	"runtime"
+	"slices"
+	"strings"
+
+	"github.com/iancoleman/strcase"
+	yaml "gopkg.in/yaml.v3"
+)
+
+// CompositeActionInput represents a Github composite action input field.
+type CompositeActionInput struct {
+	Default     string `yaml:"default"`
+	Required    bool   `yaml:"required"`
+	Description string `yaml:"description"`
+}
+
+// CompositeActionOutput represents a Github composite action output field.
+type CompositeActionOutput struct {
+	Description string `yaml:"description"`
+	Value       string `yaml:"value"`
+}
+
+type CompositeAction struct {
+	Name        string `yaml:"name"`
+	Description string `yaml:"description"`
+	Inputs      map[string]CompositeActionInput
+	Outputs     map[string]CompositeActionOutput
+	Runs        any `yaml:"runs"`
+}
+
+func (ca *CompositeAction) RequiredInputNames() []string {
+	var result []string
+	for name, input := range ca.Inputs {
+		if !input.Required {
+			continue
+		}
+		result = append(result, name)
+	}
+	slices.Sort(result)
+	return result
+}
+
+func (ca *CompositeAction) OptionalInputNames() []string {
+	var result []string
+	for name, input := range ca.Inputs {
+		if input.Required {
+			continue
+		}
+		result = append(result, name)
+	}
+	slices.Sort(result)
+	return result
+}
+
+func (ca *CompositeAction) OutputNames() []string {
+	var result []string
+	for name := range ca.Outputs {
+		result = append(result, name)
+	}
+	slices.Sort(result)
+	return result
+}
+
+func (ca *CompositeAction) WriteHeader(w io.Writer) {
+	fmt.Fprintf(w, "# %v\n", ca.Name)
+	fmt.Fprintf(w, "\n")
+	fmt.Fprintf(w, "<!-- These docs are generated by a tool -->\n")
+	fmt.Fprintf(w, "\n")
+	fmt.Fprintf(w, "%v\n", ca.Description)
+}
+
+func (ca *CompositeAction) WriteInputTable(w io.Writer) {
+	fmt.Fprintf(w, "## Inputs\n")
+	fmt.Fprintf(w, "\n")
+	fmt.Fprintf(w, "| Name | Description | Default |\n")
+	fmt.Fprintf(w, "|------|-------------|---------|\n")
+	required := ca.RequiredInputNames()
+	for _, name := range required {
+		fields := ca.Inputs[name]
+		value := "_N/A_"
+		if !fields.Required {
+			value = fmt.Sprintf("`\"%v\"`", fields.Default)
+		}
+		description := strings.ReplaceAll(fields.Description, "\n", " ")
+		fmt.Fprintf(w, "| `%v` (*) | %v | %v |\n", name, description, value)
+	}
+	for _, name := range ca.OptionalInputNames() {
+		fields := ca.Inputs[name]
+		value := fmt.Sprintf("`\"%v\"`", fields.Default)
+		description := strings.ReplaceAll(fields.Description, "\n", " ")
+		fmt.Fprintf(w, "| `%v` | %v | %v |\n", name, description, value)
+	}
+	if len(required) > 0 {
+		fmt.Fprintf(w, "\n")
+		fmt.Fprintf(w, "**Note:** _(*) marks required inputs_\n")
+	}
+
+	fmt.Fprintf(w, "\n")
+}
+
+func (ca *CompositeAction) WriteOutputTable(w io.Writer, path string) {
+	fmt.Fprintf(w, "## Outputs\n")
+	fmt.Fprintf(w, "\n")
+	if len(ca.Outputs) == 0 {
+		fmt.Fprintf(w, "`%v` does not have any outputs at this time\n", path)
+		fmt.Fprintf(w, "\n")
+	} else {
+		fmt.Fprintf(w, "| Name | Description |\n")
+		fmt.Fprintf(w, "|------|-------------|\n")
+		for _, name := range ca.OutputNames() {
+			fields := ca.Outputs[name]
+			description := strings.ReplaceAll(fields.Description, "\n", " ")
+			fmt.Fprintf(w, "| `%v` | %v |\n", name, description)
+		}
+		fmt.Fprintf(w, "\n")
+	}
+}
+
+func (ca *CompositeAction) WriteExample(w io.Writer, path, version string) {
+	id := strcase.ToKebab(strings.ReplaceAll(ca.Name, " ", "_"))
+	fmt.Fprintf(w, "## Example\n")
+	fmt.Fprintf(w, "\n")
+	fmt.Fprintf(w, "Here is a very basic example of how to use the `%v` composite action\n", path)
+	fmt.Fprintf(w, "in a project (placeholders are used in place of real inputs):\n")
+	fmt.Fprintf(w, "\n")
+	fmt.Fprintf(w, "```yaml\n")
+	fmt.Fprintf(w, "run:\n")
+	fmt.Fprintf(w, "  example-job:\n")
+	fmt.Fprintf(w, "    # ... \n")
+	fmt.Fprintf(w, "    steps:\n")
+	fmt.Fprintf(w, "      # ... \n")
+	fmt.Fprintf(w, "      - name: %v\n", ca.Name)
+	if len(ca.Outputs) > 0 {
+		output := "output"
+		if len(ca.Outputs) > 1 {
+			output = "output(s)"
+		}
+		fmt.Fprintf(w, "        id: %v # only necessary if using this action's %v\n", id, output)
+	}
+	fmt.Fprintf(w, "        uses: bitwizeshift/actions-github/%v@%v\n", path, version)
+	fmt.Fprintf(w, "        with:\n")
+	required := ca.RequiredInputNames()
+	optional := ca.OptionalInputNames()
+
+	if len(required) > 0 {
+		fmt.Fprintf(w, "          # Required inputs\n")
+		for _, name := range required {
+			value := strcase.ToScreamingSnake(name)
+			fmt.Fprintf(w, "          %v: %v\n", name, value)
+		}
+	}
+	if len(required) > 0 && len(optional) > 0 {
+		fmt.Fprintf(w, "\n")
+	}
+	if len(optional) > 0 {
+		fmt.Fprintf(w, "          # Optional inputs\n")
+		for _, name := range optional {
+			value := strcase.ToScreamingSnake(name)
+			fmt.Fprintf(w, "          %v: %v\n", name, value)
+		}
+	}
+	if len(ca.Outputs) > 0 {
+		fmt.Fprintf(w, "      # ... \n")
+		fmt.Fprintf(w, "      - name: Uses \"%v\" Outputs\n", ca.Name)
+		fmt.Fprintf(w, "        uses: example-actions/use-%v@v3 # illustrative\n", id)
+		fmt.Fprintf(w, "        with:\n")
+		for _, name := range ca.OutputNames() {
+			fmt.Fprintf(w, "          use-%v: ${{ steps.%v.outputs.%v }}\n", name, id, name)
+		}
+	}
+	fmt.Fprintf(w, "```\n")
+}
+
+func (ca *CompositeAction) WriteMarkdown(w io.Writer, path, version string) {
+	ca.WriteHeader(w)
+	ca.WriteInputTable(w)
+	ca.WriteOutputTable(w, path)
+	ca.WriteExample(w, path, version)
+}
+
+func findAllActionPaths(root string) ([]string, error) {
+	result, err := findAllActionPathsAux(root)
+	if err != nil {
+		return nil, err
+	}
+	// Force all found paths to be relative to the root
+	for i := range result {
+		result[i], _ = strings.CutPrefix(result[i], root)
+	}
+	return result, nil
+}
+
+func findAllActionPathsAux(root string) ([]string, error) {
+	var result []string
+	entries, err := os.ReadDir(root)
+	if err != nil {
+		return nil, err
+	}
+
+	for _, entry := range entries {
+		// Skip any hidden files
+		if strings.HasPrefix(entry.Name(), ".") {
+			continue
+		}
+		subpath := path.Join(root, entry.Name())
+		if entry.Type() == fs.ModeDir {
+			next, err := findAllActionPathsAux(subpath)
+			if err != nil {
+				return nil, err
+			}
+			result = append(result, next...)
+		} else if entry.Name() == "action.yaml" {
+			result = append(result, root)
+		}
+	}
+	return result, nil
+}
+
+var (
+	inpath  = flag.String("path", ".", "The input path to recursively search under")
+	version = flag.String("version", "v1", "The version to use for generated examples")
+)
+
+func sourceFileLocation() string {
+	_, file, _, _ := runtime.Caller(0)
+	return path.Dir(file)
+}
+
+func main() {
+	flag.Parse()
+
+	paths, err := findAllActionPaths(*inpath)
+	if err != nil {
+		panic(err)
+	}
+
+	outfiles := map[string]string{}
+	for _, p := range paths {
+		filepath := path.Join(p, "action.yaml")
+		file, err := os.Open(filepath)
+		if err != nil {
+			panic(err)
+		}
+		defer file.Close()
+		var action CompositeAction
+		if err := yaml.NewDecoder(file).Decode(&action); err != nil {
+			panic(err)
+		}
+		outfile := fmt.Sprintf("%v.md", strings.ReplaceAll(p, "/", "-"))
+		output := path.Join("docs", outfile)
+		writer, err := os.Create(output)
+		if err != nil {
+			panic(err)
+		}
+		defer writer.Close()
+		action.WriteMarkdown(writer, p, *version)
+		outfiles[p] = output
+	}
+	var outkeys []string
+	for file := range outfiles {
+		outkeys = append(outkeys, file)
+	}
+
+	slices.Sort(outkeys)
+	table := strings.Builder{}
+	for _, p := range outkeys {
+		outfile := outfiles[p]
+		table.WriteString(fmt.Sprintf("* [`%v`](%v)\n", p, outfile))
+	}
+	data := struct {
+		ActionTable string
+	}{
+		ActionTable: table.String(),
+	}
+
+	templateFile := path.Join(sourceFileLocation(), "README.md.template")
+	tmpl, err := template.New("README.md.template").ParseFiles(templateFile)
+	if err != nil {
+		panic(err)
+	}
+	readme, err := os.Create("README.md")
+	if err != nil {
+		panic(err)
+	}
+	defer readme.Close()
+	if err := tmpl.Execute(readme, data); err != nil {
+		panic(err)
+	}
+}