Skip to content

docs(defkit): expand definition-builder method tables to match API reference#1428

Draft
jerrinfrancis wants to merge 12 commits intokubevela:mainfrom
jerrinfrancis:revamp/defkit-definition-docs
Draft

docs(defkit): expand definition-builder method tables to match API reference#1428
jerrinfrancis wants to merge 12 commits intokubevela:mainfrom
jerrinfrancis:revamp/defkit-definition-docs

Conversation

@jerrinfrancis
Copy link
Copy Markdown
Contributor

@jerrinfrancis jerrinfrancis commented Apr 20, 2026

Description of your changes

Brings the four defkit definition-builder doc pages up to parity with the consolidated defkit-reference.html single-page reference, so the method tables users see in the docs list every public builder method instead of a curated subset.

  • docs/platform-engineers/defkit/definition-component.md — 14 → 27 methods, grouped under Metadata / Workload / Parameters & Template / Health & Status / Placement / Escape Hatches / Output.
  • docs/platform-engineers/defkit/definition-trait.md — 10 → 27 methods, split into Trait-specific (9) and Shared base (18) sections.
  • docs/platform-engineers/defkit/definition-policy.md — 3 → 19 methods, split into Policy-specific (2) and Shared base (17); documents PolicyTemplate.Set.
  • docs/platform-engineers/defkit/definition-workflowstep.md — 6 → 22 methods, split into step-specific (5) and shared (17); adds WorkflowStepTemplate (6) and BuiltinActionBuilder (5) sub-builder tables.
  • Mirrors all four files into versioned_docs/version-v1.11-alpha/platform-engineers/defkit/.

Follow-up to #1421 and #1425. Method names/signatures verified against pkg/definition/defkit/{component,trait,policy,workflow_step}.go in kubevela/kubevela.

I have:

  • Read and followed KubeVela's contribution process.
  • Update sidebar.js if adding a new page. (No new pages.)
  • Run yarn start to ensure the changes has taken effect.

Special notes for your reviewer

First pass of a larger revamp — follow-ups will extend table parity to the parameter / template / helper / collection / patch / validator pages. Opening as draft accordingly. Descriptions lifted from the in-repo defkit-reference.html, lightly trimmed.


Summary by cubic

Expands defkit docs to full API parity with the single-page defkit-reference.html, and refactors docs structure (architecture vs integration) while refreshing Quick Start. Adds concise method tables across builders and supporting pages, updates examples, and syncs all changes to versioned_docs/version-v1.11-alpha/.

  • New Features

    • Definition builders (Component, Trait, Policy, WorkflowStep): complete method tables; adds WorkflowStepTemplate and BuiltinActionBuilder sub-builders; improved examples.
    • Reference tables added across supporting pages (~350 methods): parameters (scalar/collection/complex + chain), collections API, value expressions, resource/patch builders, template outputs/helpers/trait patch ops, testing, velactx, cluster placement (label conditions + combinators), health/status DSL presets, for-each variants, workflow op builders; ships consolidated defkit-reference.html.
  • Refactors

    • Quick Start: prerequisites in a warning box (Go 1.23.8+, CUE v0.14.1+, KubeVela v1.11+); code blocks collapsible; generated CUE example moved after gen-module and updated.
    • Overview streamlined; Architecture focuses on pipeline/contract/health; Integration owns setup (example go.mod with github.com/oam-dev/kubevela v1.11.0, module layout, registration, registry query functions, ToJSON() schema, Register() placement validation note); fixes import path to github.com/oam-dev/kubevela/pkg/definition/defkit.
    • Sidebar: adds definition-register to the Defkit nav and mirrors the change in the versioned sidebar.

Written for commit fdfe0de. Summary will update on new commits.

jerrinfrancis and others added 11 commits April 20, 2026 08:53
…ity (first pass of revamp)

Signed-off-by: Jerrin Francis <jerrinfrancis7@gmail.com>
…pages (second pass of revamp)

  Add comprehensive API parameter tables from defkit-reference.html to all
  markdown documentation pages that were missing them. Tables cover ~350
  methods across parameters, templates, resources, expressions, collections,
  helpers, patches, health/status, context, placement, workflow ops,
  validators, and testing. Changes applied to both docs/ and versioned_docs/
  version-v1.11-alpha/ to keep them in sync.

Signed-off-by: Jerrin Francis <jerrinfrancis7@gmail.com>
…d CUE prerequisite

  Port kubevela#1426 to versioned_docs/v1.11-alpha:
  bump Go to 1.23.8, move generated CUE example after the gen-module
  step, and update it to match current generator output. Add CUE v0.14.1+
  as a prerequisite in both docs/ and versioned_docs/

Signed-off-by: Jerrin Francis <jerrinfrancis7@gmail.com>
Signed-off-by: Vaibhav Agrawal <vaibhav.agrawal0096@gmail.com>
…parison table with decision boxes

  Collapse Benefits subheadings into a bullet list. Replace the
  Go-vs-CUE comparison table with tip/note admonition boxes that
  focus on the decision rather than restating advantages. Remove
  the redundant info block.

Signed-off-by: Vaibhav Agrawal <vaibhav.agrawal0096@gmail.com>
  Use <details> elements to make all code blocks in quick-start.md
  collapsible, keeping the page scannable while preserving full
  examples for users who expand them.

Signed-off-by: Jerrin Francis <jerrinfrancis7@gmail.com>
…t path

  Wrap module structure and code examples in <details> elements.
  Replace placeholder import github.com/.../defkit with the full
  package path github.com/oam-dev/kubevela/pkg/definition/defkit.

Signed-off-by: Jerrin Francis <jerrinfrancis7@gmail.com>
…ical), remove duplication

  Refactor architecture.md to focus on the end-to-end pipeline, the
  Definition interface contract, and health evaluation — no code blocks.

  Refactor integration.md to own all practical setup: go.mod, module
  structure, registration pattern, CLI commands. Add registry query
  functions table, ToJSON() output schema, and Register() placement
  validation warning. Update Go to 1.23.8 and KubeVela to v1.11.0.
  Make all code blocks collapsible

Signed-off-by: Jerrin Francis <jerrinfrancis7@gmail.com>
…n Builder

Signed-off-by: Anaswara Suresh M K <anaswarasuresh22122gmail.com>
Signed-off-by: Anaswara Suresh M K <anaswarasuresh22122gmail.com>
Signed-off-by: Anaswara Suresh M K <anaswarasuresh22122gmail.com>
@vaibhav0096 vaibhav0096 force-pushed the revamp/defkit-definition-docs branch from bc34415 to f744578 Compare April 23, 2026 05:33
@vaibhav0096 vaibhav0096 force-pushed the revamp/defkit-definition-docs branch from f744578 to fdfe0de Compare April 23, 2026 05:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants