opendefensecloud / solution-arsenal / 26018460273
72%

DEFAULT BRANCH: main
Ran
Jobs 1
Files 31
Run time 1min
Badge
Embed ▾
README BADGES
x

If you need to use a raster PNG badge, change the '.svg' to '.png' in the link

Markdown

Textile

RDoc

HTML

Rst
coverage: 71.112% (-0.3%) from 71.416%
26018460273

push

github

web-flow 
fix(docs): api ref list types (#517)

## What

Closes #366

Fix the API reference generator to emit documentation sections for
`*List` resource types, resolving broken anchor links (e.g.
`[TargetList](#targetlist)`) throughout
`docs/user-guide/api-reference.md`. Add a lint check to detect upstream
template drift on future crd-ref-docs version bumps.

## Why

`crd-ref-docs` only renders a type when it has a `//
+kubebuilder:object:root=true` marker or is referenced by a field in
another type. List types satisfy neither condition — nothing declares a
field of type `TargetList`, and this project uses k8s code-gen markers
rather than kubebuilder ones. The generator still emitted
cross-reference links such as _Appears in: [TargetList](#targetlist)_
under the singular types, but the corresponding anchor never existed,
producing broken links flagged by markdownlint as `MD051`.

The fix provides custom templates via `--templates-dir`. The only change
from the crd-ref-docs defaults is one line in `type.tpl`: the render
guard is extended with `(hasSuffix "List" $type.Name)` using sprig
(already in the template function map).

The drift check (`hack/check-crd-ref-docs-templates.sh`) stores SHA256
checksums of the four upstream template files at the pinned version and
fails `lint-no-golangci` if they change, so a crd-ref-docs upgrade never
silently invalidates the patch.

## Testing

- `make docs-crd-ref` — all ten `*List` anchor links now resolve to
their sections.
- `bash hack/check-crd-ref-docs-templates.sh` — exits 0 against the
pinned version.
- Manually corrupted a checksum — script exits 1 with a diff and
remediation hint.
- `make lint-no-golangci` — passes end-to-end.

## Notes for reviewers

No CRD/API changes, no RBAC changes. When upgrading `crd-ref-docs` in
`tools.lock`, `make lint-no-golangci` will fail with a diff if the
upstream templates changed — follow the printed instructions to re-sync
and update `.upstream-checksums`.

## Checklist

- [x] ~~T... (continued)

2346 of 3299 relevant lines covered (71.11%)

32.18 hits per line

Coverage Regressions

Lines Coverage ∆ File
8
88.15
 -1.82% pkg/controller/rendertask_controller.go
4
67.77
 -0.29% pkg/controller/target_controller.go
Jobs
ID Job ID Ran Files Coverage
1 26018460273.1 31
71.11
 GitHub Action Run
Source Files on build 26018460273