Documentation
¶
Overview ¶
Package kindref writes the Spec page of each feature of the user guide's Developer chapter from funcd's OpenAPI document (ADR-0323): every field of the spec and the status of the feature's kinds, with its type, its limits and its description, each kind's tested example when it has one, and the methods a handler calls on the feature's ctx clients, read from the language shims' api.json. It also lays out the API reference of the docs site, which renders each operation from the same document (ADR-0331).
Index ¶
- Constants
- Variables
- func ReferenceFiles(doc *huma.OpenAPI, sections map[string]SectionMeta) (map[string][]byte, error)
- func ReferencePaths(doc *huma.OpenAPI) map[string]string
- func Render(doc *huma.OpenAPI) (map[string][]byte, error)
- func Undescribed(doc *huma.OpenAPI) []string
- func UndescribedOperations(doc *huma.OpenAPI) []string
- type Feature
- type SectionMeta
Constants ¶
const CommonPage = "develop/common-definitions.md"
CommonPage is the page of the definitions every kind shares, relative to docs/guide.
const Marker = "# Generated by specgen from the Go types, api/types/v1alpha1/examples and the language shims' api.json: " +
"change those, not this page."
Marker is the first front-matter line of every page Render writes; specgen deletes a page that carries it and that Render no longer returns.
Variables ¶
var Features = []Feature{ {"workloads/function", []v1.Kind{v1.KindFunction, v1.KindRevision, v1.KindInvocation}}, {"workloads/app", []v1.Kind{v1.KindApp, v1.KindAppRevision}}, {"workloads/site", []v1.Kind{v1.KindSite}}, {"workloads/workflow", []v1.Kind{v1.KindWorkflow, v1.KindWorkflowRun}}, {"workloads/configuration", []v1.Kind{v1.KindConfigMap}}, {"services/kv", []v1.Kind{v1.KindKVStore}}, {"services/bucket", []v1.Kind{v1.KindBucket}}, {"services/sql", []v1.Kind{v1.KindSQLDatabase}}, {"services/lake", []v1.Kind{v1.KindLake}}, {"services/secrets", []v1.Kind{v1.KindSecret}}, {"services/events", []v1.Kind{v1.KindEventSource, v1.KindSensor}}, {"security-and-networking/security", []v1.Kind{v1.KindIdentity, v1.KindRole, v1.KindRolesAssignment, v1.KindPolicy}}, {"security-and-networking/networking", []v1.Kind{v1.KindRoute, v1.KindEgressPolicy}}, {"tenancy-and-limits/namespaces", []v1.Kind{v1.KindNamespace, v1.KindResourceGroup}}, {"disaster-recovery", []v1.Kind{v1.KindBackup, v1.KindBackupSchedule, v1.KindRestore}}, }
Features is the table of ADR-0323 Decision 1; with Omitted it covers v1.AllKinds() once.
var Omitted = []v1.Kind{v1.KindService, v1.KindGrant, v1.KindGateway, v1.KindWorkerNode, v1.KindRuntimeClass}
Omitted kinds get no Spec: pyvvo/funcd#1438 removes the first four, and RuntimeClass gets its fields and its first reader with FEAT-0012 F139.
var TagFeatures = map[string]string{
"Hold": "disaster-recovery",
"PlatformBackup": "disaster-recovery",
"DeadLetter": "services/events",
}
TagFeatures places the operations whose tag is not a kind: Hold and PlatformBackup on "disaster-recovery", DeadLetter on "services/events" (ADR-0329 Decision 3), on that feature's Spec tab and in its section of the API reference (ADR-0331 Decision 3.2).
Functions ¶
func ReferenceFiles ¶ added in v0.45.0
ReferenceFiles returns the reference's generated files by path from the repository root, unlike Render: api/openapi/reference-paths.json, the map that ReferencePaths returns; docs/guide/api/meta.json ({root, title, description, icon "SquareCode", pages: index and the sections}); one meta.json per section ({title, icon, pages: its kinds}); and one per kind ({title: the kind, pages: its operations in order}). specgen passes the guide's sections by directory, read from their meta.json files. It fails on an operation that no section holds, on two operations that would share a page, and on a section that sections lacks.
func ReferencePaths ¶ added in v0.45.0
ReferencePaths returns the reference page of each described operation whose tag is not an Omitted kind, by operation ID: "<section>/<kind>/<name>", such as "services/kvstore/list". Paths are unique.
func Render ¶
Render returns the generated pages by path relative to docs/guide: each feature's spec.md and CommonPage.
func Undescribed ¶
Undescribed returns, sorted, the schema path ("FunctionSpec.handler") of every field that Render shows with no description, and of every field of the API reference's schemas that no Spec page shows (ADR-0331 Decision 3.2).
func UndescribedOperations ¶ added in v0.45.0
UndescribedOperations returns, sorted, the ID of every operation whose tag is not an Omitted kind and that has no summary, or no response but its success and default.
Types ¶
type Feature ¶
type Feature struct {
Path string // under docs/guide/develop, e.g. "services/kv"
Kinds []v1.Kind // in the order the page shows them
}
Feature is one page of the Developer chapter and the kinds its Spec tab lists. Its Spec page is develop/<Path>/spec.md, and its Platform page platform/<Path>.md.
type SectionMeta ¶ added in v0.45.0
type SectionMeta struct{ Title, Icon string }
SectionMeta is a guide section's title and icon, from docs/guide/develop/<section>/meta.json.
Source Files