first part of documentation and documentation automation done

.devcontainer/Dockerfile

@@ -73,7 +73,6 @@ RUN mkdir protoc${PROTOC_VERSION}
 WORKDIR /home/parigot/deps/protoc${PROTOC_VERSION}
 RUN mv ../protoc-${PROTOC_VERSION}.zip .
 RUN unzip protoc-${PROTOC_VERSION}.zip
-RUN ln -s /home/parigot/deps/protoc-${PROTOC_VERSION}/bin/protoc /home/parigot/tools/bin
 
 ## install wasmtime
 WORKDIR /home/parigot/deps
@@ -127,6 +126,7 @@ RUN ln -s /home/parigot/deps/go${GOLANG_VERSION_HOST}/bin/go /home/parigot/tools
 ## if something called "go" is not in your path, the dev container will not run
 RUN ln -s /home/parigot/deps/go${GOLANG_VERSION_HOST}/bin/go /home/parigot/tools/bin/go
 RUN ln -s /usr/local/bin/hugo /home/parigot/tools/bin
+RUN ln -s /home/parigot/deps/protoc-${PROTOC_VERSION}/bin/protoc /home/parigot/tools/bin
 
 # RUN ln -s /usr/local/tinygo/build/tinygo /home/parigot/tools/bin
 # RUN ln -s /usr/lib/llvm-15/bin/clang /home/parigot/tools/bin
@@ -181,14 +181,18 @@ ENV PROTOC_GO_VERSION=1.28.1
 ENV PROTOC_GRPC_VERSION=1.51.0
 RUN go${GOLANG_VERSION_HOST} install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
 RUN go${GOLANG_VERSION_HOST} install google.golang.org/protobuf/cmd/protoc-gen-go@v${PROTOC_GO_VERSION}
-#RUN go${GOLANG_VERSION_HOST} install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v${PROTOC_GRPC_VERSION}
-#RUN go${GOLANG_VERSION_HOST} install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
 RUN go${GOLANG_VERSION_HOST} install github.com/bufbuild/connect-go/cmd/protoc-gen-connect-go@latest
 RUN go${GOLANG_VERSION_HOST} install github.com/bufbuild/buf/cmd/buf@v1.17
 RUN go${GOLANG_VERSION_HOST} install golang.org/x/tools/gopls@latest
 RUN go${GOLANG_VERSION_HOST} install github.com/go-delve/delve/cmd/dlv@latest
 RUN go${GOLANG_VERSION_HOST} install honnef.co/go/tools/cmd/staticcheck@latest
 RUN go${GOLANG_VERSION_HOST} install github.com/kyleconroy/sqlc/cmd/sqlc@latest
+RUN go${GOLANG_VERSION_HOST} install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latest
+RUN go${GOLANG_VERSION_HOST} install  github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc
+
+
+#RUN go${GOLANG_VERSION_HOST} install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v${PROTOC_GRPC_VERSION}
+#RUN go${GOLANG_VERSION_HOST} install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
 #RUN go${GOLANG_VERSION_HOST} install github.com/onsi/ginkgo/v2/ginkgo
 
 RUN ln -s /home/parigot/go/bin/* /home/parigot/tools/bin

Makefile

@@ -212,19 +212,43 @@ test:
 .PHONY: docs
 docs:
 	#protobufs
-	protoc --doc_out=site/content/en/docs/API/Proto --doc_opt=markdown,api.md -I api/proto \
+	protoc --doc_out=site/content/en/docs/api/proto --doc_opt=markdown,api.md -I api/proto \
 	api/proto/file/v1/file.proto \
 	api/proto/syscall/v1/syscall.proto \
 	api/proto/queue/v1/queue.proto \
 	api/proto/protosupport/v1/protosupport.proto \
 	api/proto/queue/v1/queue.proto \
 	api/proto/test/v1/test.proto
-	touch site/content/en/docs/API/Proto/frontmatter_date.md
-	chmod 777 site/content/en/docs/API/Proto/frontmatter_date.md
-	cat site/content/en/docs/API/Proto/frontmatter.tmpl| sed -e "s/_date_/`date -I`/" > site/content/en/docs/API/Proto/frontmatter_date.md
-	cat site/content/en/docs/API/Proto/frontmatter_date.md site/content/en/docs/API/Proto/api.md > site/content/en/docs/API/Proto/_index.md
-	rm site/content/en/docs/API/Proto/frontmatter_date.md
-	rm site/content/en/docs/API/Proto/api.md
+	touch site/content/en/docs/api/proto/frontmatter_date.md
+	chmod 777 site/content/en/docs/api/proto/frontmatter_date.md
+	cat site/content/en/docs/api/proto/frontmatter.tmpl| sed -e "s/_date_/`date -I`/" > site/content/en/docs/api/proto/frontmatter_date.md
+	cat site/content/en/docs/api/proto/frontmatter_date.md site/content/en/docs/api/proto/api.md > site/content/en/docs/api/proto/_index.md
+	rm site/content/en/docs/api/proto/frontmatter_date.md
+	rm site/content/en/docs/api/proto/api.md
+	## guest docs
+	GOFLAGS= gomarkdoc -o site/content/en/docs/api/guest/guest.md \
+	github.com/iansmith/parigot/api/guest/... \
+	github.com/iansmith/parigot/lib/go/... \
+	github.com/iansmith/parigot/api/shared/... 
+	touch site/content/en/docs/api/guest/frontmatter_date.md
+	chmod 777 site/content/en/docs/api/guest/frontmatter_date.md
+	cat site/content/en/docs/api/guest/frontmatter.tmpl| sed -e "s/_date_/`date -I`/" > site/content/en/docs/api/guest/frontmatter_date.md
+	cat site/content/en/docs/api/guest/frontmatter_date.md site/content/en/docs/api/guest/guest.md > site/content/en/docs/api/guest/_index.md
+	rm site/content/en/docs/api/guest/frontmatter_date.md
+	rm site/content/en/docs/api/guest/guest.md
+	## plugin docs
+	GOFLAGS= gomarkdoc -o site/content/en/docs/api/plugin/plugin.md \
+	github.com/iansmith/parigot/api/plugin/... \
+	github.com/iansmith/parigot/api/plugin/file/... \
+	github.com/iansmith/parigot/api/plugin/queue/... \
+	github.com/iansmith/parigot/api/plugin/syscall/... 
+	touch site/content/en/docs/api/plugin/frontmatter_date.md
+	chmod 777 site/content/en/docs/api/plugin/frontmatter_date.md
+	cat site/content/en/docs/api/plugin/frontmatter.tmpl| sed -e "s/_date_/`date -I`/" > site/content/en/docs/api/plugin/frontmatter_date.md
+	cat site/content/en/docs/api/plugin/frontmatter_date.md site/content/en/docs/api/plugin/plugin.md > site/content/en/docs/api/plugin/_index.md
+	rm site/content/en/docs/api/plugin/frontmatter_date.md
+	rm site/content/en/docs/api/plugin/plugin.md
+	## plugin docs
 #
 # CLEAN
 #

api/shared/const.go

@@ -2,7 +2,6 @@ package apishared
 
 import (
 	"hash/crc32"
-	"time"
 	"unsafe"
 )
 
@@ -28,6 +27,8 @@ func init() {
 // off the instantiation's normal call to start so that we can control the startup and its entry point.
 const EntryPointSymbol = "_start"
 
+// In parigot the 8 byte magic value, when needed, is the date of the french
+// and us revolutions, in hex.
 var MagicStringOfBytes = uint64(0x1789071417760704)
 
 // GuestReceiveBufferSize is the maximum amount data that the guest expects to
@@ -38,24 +39,26 @@ const GuestReceiveBufferSize = WasmPageSize
 // unix domain socket for talking to the logviewer... note that the SocketEnvVar
 // should be "" when you are running an app inside the dev container.  You only
 // need SocketEnvVar for things running on the local machine, like the log viewer app.
-const SocketEnvVar = "PARIGOT_SOCKET_DIR"
-const SocketName = "logviewer.sock"
+//const SocketEnvVar = "PARIGOT_SOCKET_DIR"
+//const SocketName = "logviewer.sock"
 
 // ExpectedStackDumpSize is used to allocate space so that stack trace
 // can be placed in it, then read back line by line.
 const ExpectedStackDumpSize = 4096 * 2
 
-const FrontMatterSize = 12
-const TrailerSize = 4
-const WriteTimeout = 100 * time.Millisecond
-const ReadTimeout = 100 * time.Millisecond
-const LongReadTimeout = 500 * time.Millisecond
+// const FrontMatterSize = 12
+// const TrailerSize = 4
+// const WriteTimeout = 100 * time.Millisecond
+// const ReadTimeout = 100 * time.Millisecond
+// const LongReadTimeout = 500 * time.Millisecond
 
+// KoopmanTable is the `crc32.Koopman` data in a table ready to use for
+// CRC32 computations.
 var KoopmanTable = crc32.MakeTable(crc32.Koopman)
-var ReadBufferSize = 8192
 
-// Name of the fs we used to send/receive messages to parigot
-var FsName = "/parigotvirt"
+// ReadBuffer is the maximum amount of data you can expect to receive in
+// single read call with files or the network.
+var ReadBufferSize = 8192
 
 // The amount of time we will wait for a function call to be
 // completed.

buf.gen.yaml

@@ -8,11 +8,6 @@ plugins:
   - name: go
     out: g/
     opt: paths=source_relative
-  - name: doc
-    out: g/doc
-    opt: 
-    - doc_opt=markdown,index.md
-    #- doc_out=g/doc 
   #- name: connect-go
   #  out: proto/g/
 #    opt: paths=source_relative

site/content/en/docs/API/Proto/_index.md

@@ -1,9 +1,18 @@
 ---
-title: API/Proto
-description: Interface to parigot and built-ins
+title: Protobuf schema
+description: Protobuf specs for parigot and built in services.
 date: 2023-07-01
 weight: 1
 ---
+{{% pageinfo %}} 
+
+All of this information applies the current version of parigot, `atlanta-0.3.0`.
+Versions up to `some_city-1.0.0` carry no backward compatibility guarantees,
+promises or anything else to protect you from change..  One may assume that
+there will be significant changes in any and all publicly facing APIs and
+internal code as well.  
+
+{{% /pageinfo %}}
 
 When these protobuf files are compiled inside the parigot repository, the
 results go in the `g/` directory at the top level of the repository.

site/content/en/docs/API/Proto/frontmatter.tmpl

@@ -1,9 +1,18 @@
 ---
-title: API/Proto
-description: Interface to parigot and built-ins
+title: Protobuf schema
+description: Protobuf specs for parigot and built in services.
 date: _date_
 weight: 1
 ---
+{{% pageinfo %}} 
+
+All of this information applies the current version of parigot, `atlanta-0.3.0`.
+Versions up to `some_city-1.0.0` carry no backward compatibility guarantees,
+promises or anything else to protect you from change.  One may assume that
+there will be significant changes in any and all publicly facing APIs and
+internal code as well.  
+
+{{% /pageinfo %}}
 
 When these protobuf files are compiled inside the parigot repository, the
 results go in the `g/` directory at the top level of the repository.

site/content/en/docs/API/guest/frontmatter.tmpl

@@ -0,0 +1,28 @@
+---
+title: Guest-side API
+description: Golang guests interacting with parigot and built-in services
+date: _date_
+weight: 1
+---
+{{% pageinfo %}} 
+
+All of this information applies the current version of parigot, `atlanta-0.3.0`.
+Versions up to `some_city-1.0.0` carry no backward compatibility guarantees,
+promises or anything else to protect you from change..  One may assume that
+there will be significant changes in any and all publicly facing APIs and
+internal code as well.  
+
+{{% /pageinfo %}}
+
+{{% pageinfo %}} 
+
+We expect to have more "guest side" libraries for other languages soon.  Notable
+priorities are python and languages that compile to the Java VM. 
+
+{{% /pageinfo %}}
+
+All of these libraries are available to golang developers who are build a 
+guest application on top of parigot.  It is expected that developers using
+these libraries will be using at least [go1.23](https://go.dev/dl/) and with
+the go build environment variables `GOOS=wasip1 GOARCH=wasm` or equivalent
+command line flags.