tiltfile+cli: embed api stub files and add tilt dump api-stubs (#5574)

* tiltfile: import and go:embed api stubs

* cli: add `tilt dump api-stubs` command

* tiltfile: extract DumpApiStubs

* cli: rename to `tilt dump api-docs`

For consistency with `tilt dump cli-docs`.

* scripts: `tilt dump api-docs` into docs repo on release

* tiltfile: wildcard api directories

Co-authored-by: Matt Landis <landism@users.noreply.github.com>

* cli: dump api-docs prepends a header to each file

Includes instructions for making modifications to each file.

* scripts: pass version/date to tilt dump commands

Co-authored-by: Matt Landis <landism@users.noreply.github.com>

internal/cli/dump.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"path/filepath"
 	"strings"
 
 	"github.com/pkg/errors"
@@ -14,6 +15,7 @@ import (
 	"k8s.io/cli-runtime/pkg/genericclioptions"
 
 	"github.com/tilt-dev/tilt/internal/container"
+	"github.com/tilt-dev/tilt/internal/tiltfile"
 	"github.com/tilt-dev/tilt/pkg/model"
 )
 
@@ -31,6 +33,7 @@ and may change frequently.
 `,
 	}
 
+	result.AddCommand(newDumpApiDocsCmd())
 	result.AddCommand(newDumpWebviewCmd())
 	result.AddCommand(newDumpEngineCmd())
 	result.AddCommand(newDumpLogStoreCmd())
@@ -41,6 +44,22 @@ and may change frequently.
 	return result
 }
 
+func newDumpApiDocsCmd() *cobra.Command {
+	c := &apiDocsCmd{}
+	cmd := &cobra.Command{
+		Use:   "api-docs",
+		Short: "dump the Tiltfile api documentation stub files",
+		Long: `Dumps the api documentation stub files to the provided directory.
+
+The api stub files define the builtin functions, modules, and types used in Tiltfiles.
+`,
+		Run:  c.run,
+		Args: cobra.NoArgs,
+	}
+	cmd.Flags().StringVar(&c.dir, "dir", ".", "The directory to dump to")
+	return cmd
+}
+
 func newDumpWebviewCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "webview",
@@ -244,6 +263,25 @@ func dumpLogStore(cmd *cobra.Command, args []string) {
 	}
 }
 
+type apiDocsCmd struct {
+	dir string
+}
+
+func (a *apiDocsCmd) run(cmd *cobra.Command, args []string) {
+	stat, err := os.Stat(a.dir)
+	if err != nil || !stat.IsDir() {
+		cmdFail(fmt.Errorf("Provided name %v doesn't exist or isn't a directory", a.dir))
+	}
+	err = tiltfile.DumpApiStubs(a.dir, tiltInfo(), func(path string, e error) {
+		if e == nil {
+			fmt.Printf("wrote %s\n", filepath.Join(a.dir, path))
+		}
+	})
+	if err != nil {
+		cmdFail(fmt.Errorf("dump api-docs: %v", err))
+	}
+}
+
 func dumpJSON(reader io.Reader) error {
 	result, err := decodeJSON(reader)
 	if err != nil {

internal/tiltfile/api.go

@@ -0,0 +1,56 @@
+package tiltfile
+
+import (
+	"bytes"
+	"embed"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+
+	"github.com/tilt-dev/tilt/pkg/model"
+)
+
+//go:embed api/*.py api/*/*.py
+var api embed.FS
+
+const autoGeneratedHeader = `### AUTO-GENERATED ###
+# This file was auto-generated by 'tilt dump api-docs' as part of a Tilt release.
+# To make changes, modify the following file in the Tilt repository:
+#   internal/tiltfile/%s
+# Generated by Tilt version %s
+### AUTO-GENERATED ###
+
+`
+
+func ApiStubs() fs.FS {
+	return api
+}
+
+func WalkApiStubs(fn fs.WalkDirFunc) error {
+	return fs.WalkDir(ApiStubs(), "api", fn)
+}
+
+func DumpApiStubs(dir string, info model.TiltBuild, callback func(string, error)) error {
+	return WalkApiStubs(func(path string, d fs.DirEntry, e error) error {
+		if e != nil {
+			return e
+		}
+		var err error
+		dest := filepath.Join(dir, path)
+		if d.IsDir() {
+			err = os.MkdirAll(dest, 0755)
+		} else {
+			buf := bytes.NewBufferString(fmt.Sprintf(autoGeneratedHeader, path, info.HumanBuildStamp()))
+			var bytes []byte
+			bytes, err = api.ReadFile(path)
+			if err != nil {
+				return err
+			}
+			buf.Write(bytes)
+			err = os.WriteFile(dest, buf.Bytes(), 0644)
+		}
+		callback(path, err)
+		return err
+	})
+}