docs: SDK documentation cleanup and examples fix by efiacor · Pull Request #753 · kptdev/krm-functions-sdk

efiacor · 2026-05-07T22:09:14Z

Summary

Documentation overhaul and examples fix for the SDK repository.

Changes

New documentation:

docs/tutorial.md — end-to-end function development workflow
docs/interfaces.md — Runner vs ResourceListProcessor with code examples
docs/testing.md — golden test patterns, WRITE_GOLDEN_OUTPUT, e2e testing pointers
docs/containerizing.md — Dockerfile patterns, building, running locally
CONTRIBUTING.md — DCO, copyright, code review, AI disclosure (aligned with kpt/catalog)

Removed:

Legacy docs/ directory (TypeScript API docs, Jekyll artifacts)

Fixed:

go/get-started/ — uses //go:embed + fn.WithDocs, added metadata.yaml
go/fn/examples/ — updated go.mod to compile against current SDK
Root README.md — rewritten with better flow, accurate descriptions, pkg.go.dev link

Other:

Renamed testdata/test1/ → testdata/noop-passthrough/
Updated gcr.io/kpt-fn/ → ghcr.io/kptdev/krm-functions-catalog/ across all files
Added replace directive comments in go.mod files

Dependencies

This PR is based on #752 (feat/asmain-help-doc-filemode) for the fn.WithDocs API.

AI Disclosure

I have used AI in the creation of this PR.

I have used the following AI tools:

Kiro for documentation generation, code fixes, and review iteration

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Extend fn.AsMain with functional options to support: - --help: renders human-readable docs from embedded README markers - --doc: outputs machine-readable JSON for catalog tooling - Standalone file mode: accepts positional file args for local debugging New fn.WithDocs(readme, meta) option registers embedded content. Existing callers with no options are unaffected (backward-compatible). Adds internal/docs package with: - ParseMarkers: extracts mdtogo Short/Long/Examples sections - ParseMetadata: parses metadata.yaml content - RenderHelp/RenderDoc: formats output for --help and --doc Includes property-based tests (rapid) and unit tests for all new code. Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

Mechanical changes from 'go fix ./...': - interface{} → any (Go 1.18+ type alias) - reflect.Ptr → reflect.Pointer (deprecated constant) - strings.Index+slice → strings.Cut (Go 1.18+ idiom) Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

- Replace manual loops with slices.Contains for --help/--doc checks (matches what 'go fix' produces) - Change test file permissions from 0644 to 0600 (gosec G306) Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

…tches catalog READMEs) The catalog functions use <- All existing tests continue tomdtogo--> (bare) as the section end marker, not <- All existing tests continue tomdtogo:End-->. Updated the parser and all tests to match the real-world README format. Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

Go test runner passes -test.* flags via os.Args. The file mode arg parser must skip all flag-like arguments (starting with -), not just those starting with --. Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

- Delete legacy docs/ directory (TypeScript API docs, Jekyll artifacts) - Add docs/tutorial.md — end-to-end function development workflow - Add docs/interfaces.md — Runner vs ResourceListProcessor guide - Add docs/testing.md — golden test patterns with testhelpers - Add docs/containerizing.md — Dockerfile patterns and local testing - Add CONTRIBUTING.md aligned with kpt/catalog conventions - Rewrite README.md with better flow and accurate descriptions - Fix go/get-started/ to use //go:embed + fn.WithDocs - Fix go/fn/examples/ go.mod - Rename testdata/test1/ to testdata/noop-passthrough/ - Update gcr.io/kpt-fn/ references to ghcr.io/kptdev/krm-functions-catalog/ - Add replace directive comments in go.mod files - Update .gitignore for compiled binary Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

mpgreaves · 2026-05-27T10:53:49Z

+functions use. It accepts `BUILDER_IMAGE` and `BASE_IMAGE` as build args.
+
+For standalone functions or local development, use a multi-stage build with a
+minimal base image. The function binary should be statically linked (no CGO) so


statically linked (no CGO) so -> statically linked (no CGO), so

mpgreaves · 2026-05-27T13:45:00Z

+```
+
+Note: the image must be published and accessible from the machine running
+`kpt fn render`. For local development, build the image locally first and it


build the image locally first and it will be used

->

build the image locally first. It will be used

mpgreaves · 2026-05-27T13:47:41Z

+# Interfaces
+
+The SDK provides two interfaces for implementing KRM functions. Choose based on
+what your function needs to do.


Choose based on what your function needs to do.

->

Choose according to your function requirements.

mpgreaves · 2026-05-27T13:49:05Z

+
+Characteristics:
+- The SDK automatically parses `functionConfig` into your struct's exported fields (via JSON tags).
+- You can **modify** existing items but cannot add or remove items from the slice.


You can modify existing items but cannot add or remove

->

You can modify existing items, but you cannot add or remove

mpgreaves · 2026-05-27T13:53:42Z

+// runner implements ResourceListProcessor and can be passed to fn.AsMain
+```
+
+This wrapper handles:


This wrapper handles: -> This wrapper handles the following:

mpgreaves · 2026-05-27T13:55:06Z

+
+## Golden Test Pattern
+
+Golden tests compare function output against expected baseline files. This


Golden tests compare function output against expected baseline files.

->

Golden tests compare the function output against the expected baseline files.

mpgreaves · 2026-05-27T13:56:35Z

+go test ./...
+```
+
+If the function output doesn't match `_expected.yaml`, the test fails with a


If the function output doesn't match -> If the function output does not match

mpgreaves · 2026-05-27T13:57:28Z

+diffs in version control before committing.
+
+**Caution:** `WRITE_GOLDEN_OUTPUT` accepts whatever the function currently
+produces as "correct." If the function has a bug, you've just blessed buggy


you've just blessed -> you have just blessed

mpgreaves · 2026-05-27T13:59:26Z

+- Keep test cases focused — one behavior per test directory.
+- Use descriptive directory names (e.g., `empty-input`, `missing-namespace`, `multiple-resources`).
+- The `_fnconfig.yaml` can be empty if your function doesn't require configuration.
+- Golden tests catch unintentional formatting changes too, which helps maintain stable output.


Golden tests catch unintentional formatting changes too, which helps maintain stable output.

->

Golden tests also catch unintentional formatting changes. This helps to maintain a stable output.

mpgreaves · 2026-05-27T14:01:14Z

+The e2e runner uses a different test structure (`.expected/` directories with
+`config.yaml`, `diff.patch`, `results.yaml`) and is used by the
+[krm-functions-catalog](https://github.com/kptdev/krm-functions-catalog) `tests/`
+directory to validate functions running inside containers against `kpt fn render`.


to validate functions running inside containers -> to validate the functions running inside the containers

mpgreaves · 2026-05-27T14:02:17Z

+# Tutorial: Developing a KRM Function
+
+This tutorial walks through the end-to-end workflow for building a KRM function
+using the Go SDK. By the end, you'll have a working function with embedded


By the end, you'll have -> By the end, you will have

mpgreaves · 2026-05-27T14:02:55Z

+}
+```
+
+Here's a minimal function that sets labels on all resources:


Here's a minimal function that sets labels on all resources:

->

Here is a minimal function that sets labels on all the resources:

Copilot AI review requested due to automatic review settings May 7, 2026 22:09

efiacor requested review from kispaljr, liamfallon and mozesl-nokia as code owners May 7, 2026 22:09

Copilot started reviewing on behalf of efiacor May 7, 2026 22:09 View session

efiacor requested a review from CsatariGergely May 7, 2026 22:09

efiacor self-assigned this May 7, 2026

efiacor added documentation Improvements or additions to documentation go Pull requests that update Go code labels May 7, 2026

Copilot AI reviewed May 7, 2026

View reviewed changes

efiacor mentioned this pull request May 11, 2026

Have a convenient way to build the docker files kptdev/kpt#4309

Open

liamfallon approved these changes May 20, 2026

View reviewed changes

efiacor added 5 commits May 25, 2026 13:07

chore: gitignore rapid testdata failure files

bf78605

Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

fix: CI drift — use slices.Contains, fix file permissions

035fc21

- Replace manual loops with slices.Contains for --help/--doc checks (matches what 'go fix' produces) - Change test file permissions from 0644 to 0600 (gosec G306) Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

efiacor force-pushed the docs/sdk-documentation-cleanup branch from d67a0af to 8f9b6a2 Compare May 25, 2026 12:15

efiacor added 2 commits May 25, 2026 13:23

fix: skip single-dash flags in file mode arg parsing

c53c550

Go test runner passes -test.* flags via os.Args. The file mode arg parser must skip all flag-like arguments (starting with -), not just those starting with --. Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

efiacor force-pushed the docs/sdk-documentation-cleanup branch from 8f9b6a2 to 293bc1f Compare May 25, 2026 12:23

mpgreaves reviewed May 27, 2026

View reviewed changes


		## Golden Test Pattern

		Golden tests compare function output against expected baseline files. This

Conversation

efiacor commented May 7, 2026

Summary

Changes

Dependencies

AI Disclosure

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants