Skip to content

Commit db46fd5

Browse files
authored
Add k8s CRD types to apitool API reference generator. (agent-substrate#3591)
The `apitool generate-docs` command now adds a section with CRD types as well. Signed-off-by: Julian Gutierrez Oschmann <[email protected]>
1 parent 2d96fd6 commit db46fd5

43 files changed

Lines changed: 1785 additions & 577 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/site.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ on:
2222
- 'docs/**'
2323
- 'demos/*/README.md'
2424
- 'api/ateapi/v1/**'
25+
- 'manifests/ate-install/generated/ate.dev_*.yaml'
2526
- 'tools/apitool/**'
2627
- 'tools/site-content/**'
2728
- 'tools/site-release-data/**'
@@ -35,6 +36,7 @@ on:
3536
- 'docs/**'
3637
- 'demos/*/README.md'
3738
- 'api/ateapi/v1/**'
39+
- 'manifests/ate-install/generated/ate.dev_*.yaml'
3840
- 'tools/apitool/**'
3941
- 'tools/site-content/**'
4042
- 'tools/site-release-data/**'

‎docs/reference/api.md‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,13 @@ card_icon: "fa-solid fa-cubes"
66
layout: "api-reference"
77
body_class: "as-apiref-page"
88
description: >
9-
Resources, methods, messages, and enums of the Substrate control-plane API.
9+
Reference for the Substrate ate-api-server gRPC API and Kubernetes CRD types.
1010
---
1111

1212
# API Reference
1313

14-
The website generates the API reference from
15-
[`ateapi.proto`](../../api/ateapi/v1/ateapi.proto), which defines every
16-
resource, method, message, and enum of the control-plane API along with its
17-
documentation. Read the proto for the full reference. To change the reference,
18-
edit its doc comments, following
14+
The website generates the API reference from the ate-api-server gRPC API and the
15+
Kubernetes CRD types. To change the reference, edit the doc comments in
16+
[`ateapi.proto`](../../api/ateapi/v1/ateapi.proto) or in
17+
[`api/infra/k8s/ate/v1`](../../api/infra/k8s/ate/v1), following
1918
[Documentation Comments](../api-style-guide.md#13-documentation-comments).

‎hack/site.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
# hack/site.sh serve live-reloading dev server
2020
# hack/site.sh build production build into site/public, as CI runs it
2121
# hack/site.sh content generate site/content/ stubs from docs/ and demos/,
22-
# and the API reference from ateapi.proto
22+
# and the API reference
2323
# hack/site.sh release-data write site/data/release.json (serve and build
2424
# run this first)
2525
# hack/site.sh test build against site/testdata and check the
Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
// Copyright 2026 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
// Package generated embeds the CRD manifests next to it, for tools that need
16+
// to read them (e.g. apitool).
17+
package generated
18+
19+
import "embed"
20+
21+
//go:embed ate.dev_*.yaml
22+
var crdFiles embed.FS
23+
24+
// CRDs returns each CRD manifest's raw text.
25+
func CRDs() ([]string, error) {
26+
entries, err := crdFiles.ReadDir(".")
27+
if err != nil {
28+
return nil, err
29+
}
30+
crds := make([]string, 0, len(entries))
31+
for _, e := range entries {
32+
text, err := crdFiles.ReadFile(e.Name())
33+
if err != nil {
34+
return nil, err
35+
}
36+
crds = append(crds, string(text))
37+
}
38+
return crds, nil
39+
}

‎site/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ relative links:
4242
from `assets/api-reference/`, and the sidebar lists its resources from
4343
`nav.json` there. `hack/site.sh` fills that directory with
4444
`apitool generate-docs` (see `tools/apitool/README.md`), which generates the
45-
reference from `ateapi.proto` for main and for each release since v1.0.0.
45+
reference for main and for each release since v1.0.0.
4646
`api.md` is the page for main. The content adapter
4747
`adapters/docs/reference/api/_content.gotmpl` adds a hidden page for each
4848
release, which the page's version menu links to. The `.apiref` variables in

‎site/assets/scss/_styles_project.scss‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -481,6 +481,7 @@ footer {
481481
padding-right: 0;
482482

483483
> .td-main {
484+
width: 100%;
484485
max-width: 1440px;
485486
margin: 0 auto;
486487
padding: 0 40px;
@@ -3985,6 +3986,14 @@ footer {
39853986
}
39863987
}
39873988

3989+
.as-sb__tree-group {
3990+
display: block;
3991+
padding: 8px 10px 2px;
3992+
color: $substrate-text;
3993+
font-size: 12px;
3994+
font-weight: 600;
3995+
}
3996+
39883997
.as-sb__tree-link {
39893998
display: block;
39903999
padding: 4px 10px;

‎site/layouts/_partials/api-reference-nav.html‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,18 @@
1616

1717
{{/*
1818
Renders the API reference's resource tree in the sidebar, under the
19-
reference page's link. Call with the decoded nodes of apitool's nav.json.
19+
reference page's link. Call with the decoded nodes of apitool's nav.json. A
20+
node without an anchor groups the resources of one API.
2021
*/ -}}
2122

2223
<ul class="as-sb__tree">
2324
{{- range . }}
2425
<li>
26+
{{- if .anchor }}
2527
<a href="#{{ .anchor }}" class="as-sb__tree-link">{{ .label }}</a>
28+
{{- else }}
29+
<span class="as-sb__tree-group">{{ .label }}</span>
30+
{{- end }}
2631
{{- with .children }}{{ partial "api-reference-nav.html" . }}{{ end }}
2732
</li>
2833
{{- end }}

‎tools/apitool/README.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,10 +41,9 @@ go test ./internal/validate/... -run TestExemptions
4141
Generates the website's API reference. `hack/site.sh content` runs it before
4242
each site build, writing to `site/assets/api-reference/`:
4343

44-
- `latest/`, from this checkout's `ateapi.proto`, and with `--releases-since`
45-
a directory per release tagged since, read from git. Each holds
46-
`reference.html`, the page body, and `nav.json`, the resource tree the
47-
site's sidebar lists.
44+
- `latest/`, from this checkout, and with `--releases-since` a directory per
45+
release tagged since, read from git. Each holds `reference.html`, the page
46+
body, and `nav.json`, the resource tree the site's sidebar lists.
4847
- `versions.json`, the version names, newest first.
4948
- `style.css` and `search.js`, which every version's page loads. The site's
5049
theme sets the colors (see `site/README.md`).

‎tools/apitool/go.mod‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,21 +7,74 @@ toolchain go1.27.3
77
replace go.ate.dev/substrate => ../..
88

99
require (
10+
github.com/alecthomas/chroma/v2 v2.27.0
1011
github.com/bufbuild/protocompile v0.14.1
1112
github.com/google/go-cmp v0.7.0
1213
github.com/spf13/cobra v1.10.2
1314
github.com/yuin/goldmark v1.8.5
1415
go.ate.dev/substrate v0.0.0-00010101000000-000000000000
1516
google.golang.org/protobuf v1.36.12
17+
k8s.io/apiextensions-apiserver v0.36.1
18+
sigs.k8s.io/yaml v1.6.0
1619
)
1720

1821
require (
22+
cel.dev/expr v0.25.2 // indirect
23+
github.com/antlr4-go/antlr/v4 v4.13.1 // indirect
24+
github.com/beorn7/perks v1.0.1 // indirect
25+
github.com/blang/semver/v4 v4.0.0 // indirect
26+
github.com/cespare/xxhash/v2 v2.3.0 // indirect
27+
github.com/dlclark/regexp2/v2 v2.2.1 // indirect
28+
github.com/fxamacker/cbor/v2 v2.9.1 // indirect
29+
github.com/go-logr/logr v1.4.4 // indirect
30+
github.com/go-openapi/jsonpointer v1.0.0 // indirect
31+
github.com/go-openapi/jsonreference v1.0.0 // indirect
32+
github.com/go-openapi/swag v0.28.0 // indirect
33+
github.com/go-openapi/swag/cmdutils v0.28.0 // indirect
34+
github.com/go-openapi/swag/conv v0.28.0 // indirect
35+
github.com/go-openapi/swag/fileutils v0.28.0 // indirect
36+
github.com/go-openapi/swag/jsonutils v0.28.0 // indirect
37+
github.com/go-openapi/swag/loading v0.28.0 // indirect
38+
github.com/go-openapi/swag/mangling v0.28.0 // indirect
39+
github.com/go-openapi/swag/netutils v0.28.0 // indirect
40+
github.com/go-openapi/swag/pools v0.28.0 // indirect
41+
github.com/go-openapi/swag/stringutils v0.28.0 // indirect
42+
github.com/go-openapi/swag/typeutils v0.28.0 // indirect
43+
github.com/go-openapi/swag/yamlutils v0.28.0 // indirect
44+
github.com/google/cel-go v0.31.0 // indirect
45+
github.com/google/gnostic-models v0.7.0 // indirect
1946
github.com/inconshreveable/mousetrap v1.1.0 // indirect
47+
github.com/json-iterator/go v1.1.12 // indirect
48+
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
49+
github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee // indirect
50+
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
51+
github.com/prometheus/client_golang v1.24.1 // indirect
52+
github.com/prometheus/client_model v0.6.2 // indirect
53+
github.com/prometheus/common v0.70.1 // indirect
54+
github.com/prometheus/procfs v0.21.1 // indirect
2055
github.com/spf13/pflag v1.0.10 // indirect
56+
github.com/x448/float16 v0.8.4 // indirect
57+
go.opentelemetry.io/otel v1.45.0 // indirect
58+
go.opentelemetry.io/otel/trace v1.45.0 // indirect
59+
go.yaml.in/yaml/v2 v2.4.4 // indirect
60+
go.yaml.in/yaml/v3 v3.0.5 // indirect
61+
golang.org/x/exp v0.0.0-20260718201538-764159d718ef // indirect
2162
golang.org/x/net v0.60.0 // indirect
2263
golang.org/x/sync v0.23.0 // indirect
2364
golang.org/x/sys v0.48.0 // indirect
2465
golang.org/x/text v0.42.0 // indirect
66+
google.golang.org/genproto/googleapis/api v0.0.0-20260803160001-6ac0973c030d // indirect
2567
google.golang.org/genproto/googleapis/rpc v0.0.0-20260803160001-6ac0973c030d // indirect
2668
google.golang.org/grpc v1.83.2 // indirect
69+
gopkg.in/inf.v0 v0.9.1 // indirect
70+
k8s.io/api v0.37.0 // indirect
71+
k8s.io/apimachinery v0.37.0 // indirect
72+
k8s.io/apiserver v0.36.1 // indirect
73+
k8s.io/component-base v0.36.1 // indirect
74+
k8s.io/klog/v2 v2.140.0 // indirect
75+
k8s.io/kube-openapi v0.0.0-20260721132016-d427ff9ee9ad // indirect
76+
k8s.io/utils v0.0.0-20260626114624-be93311217bd // indirect
77+
sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730 // indirect
78+
sigs.k8s.io/randfill v1.0.0 // indirect
79+
sigs.k8s.io/structured-merge-diff/v6 v6.4.2 // indirect
2780
)

0 commit comments

Comments
 (0)