docs: SDK documentation cleanup and examples fix#753
Open
efiacor wants to merge 8 commits intokptdev:mainfrom
Open
docs: SDK documentation cleanup and examples fix#753efiacor wants to merge 8 commits intokptdev:mainfrom
efiacor wants to merge 8 commits intokptdev:mainfrom
Conversation
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>
Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>
- --help now always takes precedence over --doc regardless of arg order - Updated AsMain doc comment to document all invocation modes - Removed no-op strings.TrimPrefix in test assertion 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>
- 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>
efiacor
requested review from
kispaljr,
liamfallon and
mozesl-nokia
as code owners
efiacor
added
documentation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documentation overhaul and examples fix for the SDK repository.
Changes
New documentation:
docs/tutorial.md— end-to-end function development workflowdocs/interfaces.md— Runner vs ResourceListProcessor with code examplesdocs/testing.md— golden test patterns, WRITE_GOLDEN_OUTPUT, e2e testing pointersdocs/containerizing.md— Dockerfile patterns, building, running locallyCONTRIBUTING.md— DCO, copyright, code review, AI disclosure (aligned with kpt/catalog)Removed:
docs/directory (TypeScript API docs, Jekyll artifacts)Fixed:
go/get-started/— uses//go:embed+fn.WithDocs, addedmetadata.yamlgo/fn/examples/— updated go.mod to compile against current SDKREADME.md— rewritten with better flow, accurate descriptions, pkg.go.dev linkOther:
testdata/test1/→testdata/noop-passthrough/gcr.io/kpt-fn/→ghcr.io/kptdev/krm-functions-catalog/across all filesDependencies
This PR is based on #752 (feat/asmain-help-doc-filemode) for the
fn.WithDocsAPI.AI Disclosure
I have used AI in the creation of this PR.
I have used the following AI tools: