feat: automatic generation for API

.github/workflows/build-artifacts-and-draft-release.yml

@@ -92,6 +92,7 @@ jobs:
           cat ./linux/cy*checksums.txt >> checksums.txt
           rm ./darwin/cy*checksums.txt
           rm ./linux/cy*checksums.txt
+          rm cy
       - name: Release
         uses: goreleaser/goreleaser-action@v5
         with:

.github/workflows/docs.yml

@@ -23,8 +23,10 @@ jobs:
           mkdir mdbook
           curl -sSL $url | tar -xz --directory=./mdbook
           echo `pwd`/mdbook >> $GITHUB_PATH
+
       - name: Build book
         run: |
+          go run cmd/docs/main.go api > docs/src/generated-api.md
           cd docs
           mdbook build
 

cmd/docs/main.go

@@ -3,6 +3,8 @@ package main
 import (
 	"context"
 	"fmt"
+	"sort"
+	"strings"
 
 	"github.com/cfoust/cy/pkg/cy"
 	"github.com/cfoust/cy/pkg/janet"
@@ -20,6 +22,11 @@ var CLI struct {
 	} `cmd:"" help:"Generate Markdown for the full API."`
 }
 
+type Symbol struct {
+	Name, Docstring, Link string
+	Macro                 bool
+}
+
 func main() {
 	ctx := kong.Parse(&CLI,
 		kong.Name("cy-docs"),
@@ -45,14 +52,68 @@ func main() {
 			panic(err)
 		}
 
+		symbols := make([]Symbol, 0)
 		cy.Callback("cy/doc", func(name string, docstring string, link string, macro bool) {
-			fmt.Printf("%s %s %t\n", name, docstring, macro)
+			symbols = append(symbols, Symbol{
+				Name:      name,
+				Docstring: docstring,
+				Link:      link,
+				Macro:     macro,
+			})
 		})
 
 		err = cy.Execute(ctx, GEN_API)
 		if err != nil {
 			panic(err)
 		}
+
+		sort.SliceStable(symbols, func(i, j int) bool {
+			return symbols[i].Name < symbols[j].Name
+		})
+
+		var output string
+
+		// Generate the table of contents
+		output += "## Index\n\n"
+		for _, symbol := range symbols {
+			header := strings.Map(func(r rune) rune {
+				if r == '/' {
+					return -1
+				}
+
+				return r
+			}, symbol.Name)
+
+			output += fmt.Sprintf("[%s](#%s) ", symbol.Name, header)
+		}
+
+		output += "\n\n---\n"
+
+		for _, symbol := range symbols {
+			_type := "function"
+
+			if symbol.Macro {
+				_type = "macro"
+			}
+
+			source := ""
+			if len(symbol.Link) > 0 {
+				source = fmt.Sprintf("[source](%s)\n", symbol.Link)
+			}
+
+			output += fmt.Sprintf(`
+#### %s
+
+_%s_
+
+%s
+%s
+
+---
+`, symbol.Name, _type, source, symbol.Docstring)
+		}
+
+		fmt.Println(output)
 	default:
 		panic(ctx.Command())
 	}

docs/src/.gitignore

@@ -0,0 +1 @@
+/generated-api.md

docs/src/api.md

@@ -3,3 +3,5 @@
 This is a complete listing of all of the API functions that `cy` provides in the top-level Janet environment (ie you do not need to `import` or `use` anything.)
 
 Janet code executed with `cy` can also access everything from [Janet's standard library](https://janet-lang.org/api/index.html) except for anything in `spork`. In addition, Janet's `ev` family of functions probably will not work; I have never tested them.
+
+{{#include generated-api.md}}