From 9f8d24b29cdb38b51392ee66225c731eba088e25 Mon Sep 17 00:00:00 2001 From: abhinav-phi Date: Fri, 4 Sep 2026 20:23:48 +0530 Subject: [PATCH 1/2] gen-apidocs: include create-only resources in the generated ToC IsTopLevelResource only recognized resources with a List operation, so group-based ToC generation (auto-detect) skipped resources that only support Create. This dropped the authentication.k8s.io group (TokenRequest, TokenReview, SelfSubjectReview) and the authorization.k8s.io review types (SubjectAccessReview and friends) from the generated navigation: their group directories and category pages were never emitted, even though the group-versions page lists them. Treat a top-level Create operation as evidence of a top-level resource as well. For TokenRequest this also required attaching the Write Operations category to the definition in the special case that maps it to the createCoreV1NamespacedServiceAccountToken operation (the category was built and the operation linked, but never appended to OperationCategories, so the operation type stayed empty and the definition still failed the check). With --auto-detect --backend=hugo-md on the v1.36 spec this emits authentication/ (token-request-v1, token-review-v1, self-subject-review-v1) and authorization/ (subject-access-review-v1, local-subject-access-review-v1, self-subject-access-review-v1, self-subject-rules-review-v1), matching the pages published up to the v1.35 docs. Signed-off-by: abhinav-phi --- gen-apidocs/generators/api/config.go | 4 ++++ gen-apidocs/generators/api/definition.go | 15 +++++++++++++++ 2 files changed, 19 insertions(+) diff --git a/gen-apidocs/generators/api/config.go b/gen-apidocs/generators/api/config.go index 5b36a23de3..cd941b76bb 100644 --- a/gen-apidocs/generators/api/config.go +++ b/gen-apidocs/generators/api/config.go @@ -831,10 +831,14 @@ func (c *Config) mapOperationsToDefinitions() error { o.Definition = d o.Definition.InToc = true + o.Type = ot if err := o.initExample(c); err != nil { return fmt.Errorf("failed to init example: %w", err) } oc.Operations = append(oc.Operations, o) + // Attach the category to the definition so IsTopLevelResource + // and the resource pages see this Create operation. + d.OperationCategories = append(d.OperationCategories, &oc) } continue } diff --git a/gen-apidocs/generators/api/definition.go b/gen-apidocs/generators/api/definition.go index adb366d2ba..514d648b77 100644 --- a/gen-apidocs/generators/api/definition.go +++ b/gen-apidocs/generators/api/definition.go @@ -337,6 +337,8 @@ func (s *Definitions) FindNewestVersion(group, kind string) string { // IsTopLevelResource returns true if this definition represents a top-level // API resource (one that has its own List endpoint), as opposed to a // subresource (Scale, Eviction) or utility type (Status, WatchEvent). +// Some resources, such as TokenRequest and the SubjectAccessReview family, +// only support Create; they are top-level resources too. func (d *Definition) IsTopLevelResource() bool { for _, c := range d.OperationCategories { if c == nil || c.Name != "Read Operations" { @@ -351,6 +353,19 @@ func (d *Definition) IsTopLevelResource() bool { } } } + for _, c := range d.OperationCategories { + if c == nil || c.Name != "Write Operations" { + continue + } + for _, op := range c.Operations { + if op == nil { + continue + } + if op.Type.Name == "Create" { + return true + } + } + } return false } From 9cecf0f6851594d8af53175a2525b7cdb8d38d02 Mon Sep 17 00:00:00 2001 From: abhinav-phi Date: Mon, 7 Sep 2026 23:39:07 +0530 Subject: [PATCH 2/2] gen-apidocs: address review on create-only ToC fix - IsTopLevelResource: single pass over OperationCategories with a switch, and a doc comment that no longer claims List-only resources are excluded - TokenRequest special case: drop the redundant o.Definition.InToc line; attaching the Write Operations category is what places the definition - Reword the XXX comment to explain why TokenRequest's operation ID does not match the generic pattern Signed-off-by: abhinav-phi --- gen-apidocs/generators/api/config.go | 5 ++-- gen-apidocs/generators/api/definition.go | 37 ++++++++++-------------- 2 files changed, 19 insertions(+), 23 deletions(-) diff --git a/gen-apidocs/generators/api/config.go b/gen-apidocs/generators/api/config.go index cd941b76bb..4aa5ea5fb2 100644 --- a/gen-apidocs/generators/api/config.go +++ b/gen-apidocs/generators/api/config.go @@ -816,7 +816,9 @@ func (c *Config) mapOperationsToDefinitions() error { continue } - // XXX: The TokenRequest definition has operation defined as "createCoreV1NamespacedServiceAccountToken"! + // TokenRequest is created through a ServiceAccount subresource, so its + // operation ID doesn't follow the ${group}${version}${resource} pattern + // the generic matcher below uses. if d.Name == "TokenRequest" && d.Group.String() == "authentication" && d.Version == "v1" { operationId := "createCoreV1NamespacedServiceAccountToken" if o, ok := c.Operations[operationId]; ok { @@ -830,7 +832,6 @@ func (c *Config) mapOperationsToDefinitions() error { } o.Definition = d - o.Definition.InToc = true o.Type = ot if err := o.initExample(c); err != nil { return fmt.Errorf("failed to init example: %w", err) diff --git a/gen-apidocs/generators/api/definition.go b/gen-apidocs/generators/api/definition.go index 514d648b77..b4931732ec 100644 --- a/gen-apidocs/generators/api/definition.go +++ b/gen-apidocs/generators/api/definition.go @@ -334,35 +334,30 @@ func (s *Definitions) FindNewestVersion(group, kind string) string { return newest } -// IsTopLevelResource returns true if this definition represents a top-level -// API resource (one that has its own List endpoint), as opposed to a -// subresource (Scale, Eviction) or utility type (Status, WatchEvent). -// Some resources, such as TokenRequest and the SubjectAccessReview family, -// only support Create; they are top-level resources too. +// IsTopLevelResource reports whether this definition is a top-level API +// resource, as opposed to a utility type (Status, WatchEvent) or a field type +// that never appears on the wire by itself. +// +// A List endpoint is the usual marker, but create-only resources such as +// TokenRequest and the SubjectAccessReview family qualify too. func (d *Definition) IsTopLevelResource() bool { for _, c := range d.OperationCategories { - if c == nil || c.Name != "Read Operations" { + if c == nil { continue } for _, op := range c.Operations { if op == nil { continue } - if op.Type.Name == "List" || op.Type.Name == "List All Namespaces" { - return true - } - } - } - for _, c := range d.OperationCategories { - if c == nil || c.Name != "Write Operations" { - continue - } - for _, op := range c.Operations { - if op == nil { - continue - } - if op.Type.Name == "Create" { - return true + switch c.Name { + case "Read Operations": + if op.Type.Name == "List" || op.Type.Name == "List All Namespaces" { + return true + } + case "Write Operations": + if op.Type.Name == "Create" { + return true + } } } }