docs: document go sdk with examples

Signed-off-by: Alan Clucas <[email protected]>

Author: Joibel

.github/workflows/ci-build.yaml

@@ -268,6 +268,9 @@ jobs:
           - test: test-plugins
             profile: plugins
             use-api: false
+          - test: test-go-sdk
+            profile: minimal
+            use-api: true
           - test: test-java-sdk
             profile: minimal
             use-api: true

.spelling

@@ -175,6 +175,7 @@ errored
 expr
 fibonacci
 finalizer
+gRPC
 gitops
 goroutine
 goroutines
@@ -192,6 +193,7 @@ k8s-jobs
 kube
 kube-apiserver
 kube-scheduler
+kubeconfig
 kubectl
 kubelet
 kubernetes

Makefile

@@ -161,6 +161,7 @@ TOOL_SWAGGER                := $(GOPATH)/bin/swagger
 TOOL_GOIMPORTS              := $(GOPATH)/bin/goimports
 TOOL_GOLANGCI_LINT          := $(GOPATH)/bin/golangci-lint
 TOOL_GOTESTSUM              := $(GOPATH)/bin/gotestsum
+TOOL_SNIPDOC                := $(HOME)/.local/bin/snipdoc
 
 # npm bin -g will do this on later npms than we have
 NVM_BIN                     ?= $(shell npm config get prefix)/bin
@@ -225,7 +226,7 @@ SWAGGER_FILES := pkg/apiclient/_.primary.swagger.json \
 	pkg/apiclient/workflowtemplate/workflow-template.swagger.json \
 	pkg/apiclient/sync/sync.swagger.json
 PROTO_BINARIES := $(TOOL_PROTOC_GEN_GOGO) $(TOOL_PROTOC_GEN_GOGOFAST) $(TOOL_GOIMPORTS) $(TOOL_PROTOC_GEN_GRPC_GATEWAY) $(TOOL_PROTOC_GEN_SWAGGER) $(TOOL_CLANG_FORMAT)
-GENERATED_DOCS := docs/fields.md docs/cli/argo.md docs/workflow-controller-configmap.md docs/metrics.md
+GENERATED_DOCS := docs/fields.md docs/cli/argo.md docs/workflow-controller-configmap.md docs/metrics.md docs/go-sdk-guide.md
 
 # protoc,my.proto
 define protoc
@@ -449,6 +450,12 @@ ifneq ($(USE_NIX), true)
 	go install gotest.tools/[email protected]
 endif
 
+$(TOOL_SNIPDOC): Makefile
+# update this in Nix when upgrading it here
+ifneq ($(USE_NIX), true)
+	./hack/install-snipdoc.sh $(TOOL_SNIPDOC) v0.1.12
+endif
+
 $(TOOL_CLANG_FORMAT):
 ifeq (, $(shell which clang-format))
 ifeq ($(shell uname),Darwin)
@@ -821,6 +828,9 @@ docs/workflow-controller-configmap.md: config/*.go hack/docs/workflow-controller
 docs/cli/argo.md: $(CLI_PKG_FILES) go.sum ui/dist/app/index.html hack/docs/cli.go
 	go run ./hack/docs cli
 
+docs/go-sdk-guide.md: $(TOOL_SNIPDOC)
+	$(TOOL_SNIPDOC) run
+
 $(TOOL_MDSPELL): Makefile
 # update this in Nix when upgrading it here
 ifneq ($(USE_NIX), true)
@@ -968,3 +978,7 @@ pkg/apiclient/artifact/artifact.swagger.json: $(PROTO_BINARIES) $(TYPES) pkg/api
 
 # Add artifact-proto to swagger dependencies
 swagger: pkg/apiclient/artifact/artifact.swagger.json
+
+.PHONY: test-go-sdk
+test-go-sdk: ## Run all Go SDK examples
+	./hack/test-go-sdk.sh

docs/client-libraries.md

@@ -7,18 +7,35 @@ yourself. You can use a client library for the programming language you are usin
 
 Client libraries often handle common tasks such as authentication for you.
 
-## Auto-generated client libraries
+## Client Libraries
 
-The following client libraries are auto-generated using [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator-cli).
-Please expect very minimal support from the Argo team.
+We have libraries for the following languages:
 
-| Language | Client Library                                                                                    | Examples/Docs                                                                                                         |
-|----------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
-| Golang   | [`apiclient.go`](https://github.com/argoproj/argo-workflows/blob/main/pkg/apiclient/apiclient.go) | [Example](https://github.com/argoproj/argo-workflows/blob/main/cmd/argo/commands/submit.go)                           |
-| Java     | [Java](https://github.com/argoproj/argo-workflows/blob/main/sdks/java)                            |                                                                                                                       |
-| Python   | ⚠️ deprecated [Python](https://github.com/argoproj/argo-workflows/blob/main/sdks/python)           | Use [Hera](#hera-python-sdk) instead. Will be removed in version 3.7 |
+* [Go](#go-sdk)
+* [Java](#java-sdk)
+* [Python](#hera-python-sdk)
 
-## Hera Python SDK
+Please feel free to contribute more language libraries to help improve the Argo Workflows ecosystem.
+
+### Go SDK
+
+The [Go SDK](./go-sdk-guide.md) is a fully-featured client for Argo Workflows. It provides two client approaches:
+
+* **Kubernetes Client** - Direct CRD access for in-cluster applications
+* **Argo Server Client** - gRPC/HTTP access for remote applications
+
+**Documentation:**
+
+* [Go SDK Guide](./go-sdk-guide.md) - Comprehensive documentation
+* [Examples](https://github.com/argoproj/argo-workflows/blob/main/sdks/go/) - Working code examples
+* [API Reference](https://pkg.go.dev/github.com/argoproj/argo-workflows/v3)
+
+### Java SDK
+
+The [Java](https://github.com/argoproj/argo-workflows/blob/main/sdks/java) library is auto-generated using OpenAPI Generator.
+It is community supported.
+
+### Hera Python SDK
 
 Hera is the go-to Python SDK to make Argo Workflows simple and intuitive. It goes beyond a basic REST interface,
 allowing you to easily turn Python functions into script templates, and write whole Workflows in Python: