Skip to content

Commit afce327

Browse files
notandynotandy
committed
Add API documentation and auto-generation
1 parent e2dd9eb commit afce327

File tree

9 files changed

+1193
-4
lines changed

9 files changed

+1193
-4
lines changed

‎.github/workflows/update-api.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# SPDX-FileCopyrightText: Copyright 2024 SAP SE or an SAP affiliate company and cobaltcore-dev contributors
2+
#
3+
# SPDX-License-Identifier: Apache-2.0
4+
5+
name: Update API Docs
6+
on:
7+
schedule:
8+
- cron: "0 0 * * 0" # Runs every Sunday at midnight
9+
workflow_dispatch:
10+
11+
jobs:
12+
update-api:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- name: Checkout this repository
16+
uses: actions/checkout@v5
17+
- name: Checkout openstack-hypervisor-operator repository
18+
uses: actions/checkout@v5
19+
with:
20+
repository: cobaltcore-dev/openstack-hypervisor-operator
21+
path: openstack-hypervisor-operator
22+
- name: Checkout kvm-node-agent repository
23+
uses: actions/checkout@v5
24+
with:
25+
repository: cobaltcore-dev/kvm-node-agent
26+
path: kvm-node-agent
27+
- name: Install crdoc
28+
uses: jaxxstorm/[email protected]
29+
with: # Grab the latest version
30+
repo: fybrik/crdoc
31+
tag: v0.6.4
32+
- name: Run crdoc to update api
33+
run: |
34+
crdoc generate --template frontmatter.tmpl --resources openstack-hypervisor-operator/config/crd/bases/kvm.cloud.sap_evictions.yaml --toc hack/template/eviction.yaml --output docs/api/kvm.cloud.sap/v1/eviction.md
35+
crdoc generate --template frontmatter.tmpl --resources openstack-hypervisor-operator/config/crd/bases/kvm.cloud.sap_hypervisors.yaml --toc hack/template/hypervisor.yaml --output docs/api/kvm.cloud.sap/v1/hypervisor.md
36+
crdoc generate --template frontmatter.tmpl --resources kvm-node-agent/config/crd/bases/kvm.cloud.sap_migrations.yaml --toc hack/template/migration.yaml --output docs/api/kvm.cloud.sap/v1alpha1/migration.md
37+
- name: Commit changes
38+
run: |
39+
if ! command -v git &> /dev/null; then
40+
sudo apt-get update && sudo apt-get install git -y
41+
fi
42+
git config --global user.name "github-actions[bot]"
43+
git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
44+
git add docs/api/*.md
45+
git commit -m "Update API docs" || echo "No changes to commit"
46+
git push
47+
env:
48+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎docs/.vitepress/config.mts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ export default defineConfig(withMermaid({
4343

4444
sidebar: generateSidebar({
4545
documentRootPath: '/docs/',
46-
capitalizeFirst: true,
46+
capitalizeFirst: false,
4747
useTitleFromFileHeading: false,
4848
useTitleFromFrontmatter: true,
4949
useFolderLinkFromIndexFile: true,

‎docs/api/index.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@ title: API Reference
44

55
# API Reference
66

7-
::: warning
8-
Under construction
9-
:::
7+
The CobaltCore API reference provides detailed information about the custom resources and their specifications used within the CobaltCore environment. This documentation is intended for developers and operators who need to interact with or extend the functionality of CobaltCore.
8+
9+
## Packages
10+
- [kvm.cloud.sap/v1/hypervisor](kvm.cloud.sap/v1/hypervisor) Hypervisor CRD
11+
- [kvm.cloud.sap/v1/eviction](kvm.cloud.sap/v1/eviction) Eviction CRD
12+
- [kvm.cloud.sap/v1alpha1/migration](kvm.cloud.sap/v1alpha1/migration) Migration CRD

‎docs/api/kvm.cloud.sap/v1/eviction.md‎

Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
---
2+
title: Eviction
3+
weight: 1
4+
description: Eviction CRD
5+
---
6+
7+
Packages:
8+
9+
- [kvm.cloud.sap/v1](#kvmcloudsapv1)
10+
11+
# kvm.cloud.sap/v1
12+
13+
Resource Types:
14+
15+
- [Eviction](#eviction)
16+
17+
18+
19+
20+
## Eviction
21+
<sup><sup>[↩ Parent](#kvmcloudsapv1 )</sup></sup>
22+
23+
24+
25+
26+
27+
28+
Eviction is the Schema for the evictions API
29+
30+
<table>
31+
<thead>
32+
<tr>
33+
<th>Name</th>
34+
<th>Type</th>
35+
<th>Description</th>
36+
<th>Required</th>
37+
</tr>
38+
</thead>
39+
<tbody><tr>
40+
<td><b>apiVersion</b></td>
41+
<td>string</td>
42+
<td>kvm.cloud.sap/v1</td>
43+
<td>true</td>
44+
</tr>
45+
<tr>
46+
<td><b>kind</b></td>
47+
<td>string</td>
48+
<td>Eviction</td>
49+
<td>true</td>
50+
</tr>
51+
<tr>
52+
<td><b><a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta">metadata</a></b></td>
53+
<td>object</td>
54+
<td>Refer to the Kubernetes API documentation for the fields of the `metadata` field.</td>
55+
<td>true</td>
56+
</tr><tr>
57+
<td><b><a href="#evictionspec">spec</a></b></td>
58+
<td>object</td>
59+
<td>
60+
EvictionSpec defines the desired state of Eviction<br/>
61+
</td>
62+
<td>false</td>
63+
</tr><tr>
64+
<td><b><a href="#evictionstatus">status</a></b></td>
65+
<td>object</td>
66+
<td>
67+
EvictionStatus defines the observed state of Eviction<br/>
68+
</td>
69+
<td>false</td>
70+
</tr></tbody>
71+
</table>
72+
73+
74+
### Eviction.spec
75+
<sup><sup>[↩ Parent](#eviction)</sup></sup>
76+
77+
78+
79+
EvictionSpec defines the desired state of Eviction
80+
81+
<table>
82+
<thead>
83+
<tr>
84+
<th>Name</th>
85+
<th>Type</th>
86+
<th>Description</th>
87+
<th>Required</th>
88+
</tr>
89+
</thead>
90+
<tbody><tr>
91+
<td><b>hypervisor</b></td>
92+
<td>string</td>
93+
<td>
94+
Name of hypervisor to evict<br/>
95+
<br/>
96+
<i>Validations</i>:<li>self == oldSelf: Value is immutable</li>
97+
</td>
98+
<td>true</td>
99+
</tr><tr>
100+
<td><b>reason</b></td>
101+
<td>string</td>
102+
<td>
103+
Reason for eviction, always required<br/>
104+
</td>
105+
<td>true</td>
106+
</tr></tbody>
107+
</table>
108+
109+
110+
### Eviction.status
111+
<sup><sup>[↩ Parent](#eviction)</sup></sup>
112+
113+
114+
115+
EvictionStatus defines the observed state of Eviction
116+
117+
<table>
118+
<thead>
119+
<tr>
120+
<th>Name</th>
121+
<th>Type</th>
122+
<th>Description</th>
123+
<th>Required</th>
124+
</tr>
125+
</thead>
126+
<tbody><tr>
127+
<td><b><a href="#evictionstatusconditionsindex">conditions</a></b></td>
128+
<td>[]object</td>
129+
<td>
130+
Conditions is an array of current conditions<br/>
131+
</td>
132+
<td>false</td>
133+
</tr><tr>
134+
<td><b>hypervisorServiceId</b></td>
135+
<td>string</td>
136+
<td>
137+
<br/>
138+
</td>
139+
<td>false</td>
140+
</tr><tr>
141+
<td><b>outstandingInstances</b></td>
142+
<td>[]string</td>
143+
<td>
144+
<br/>
145+
</td>
146+
<td>false</td>
147+
</tr><tr>
148+
<td><b>outstandingRamMb</b></td>
149+
<td>integer</td>
150+
<td>
151+
<br/>
152+
<br/>
153+
<i>Format</i>: int64<br/>
154+
<i>Default</i>: 0<br/>
155+
</td>
156+
<td>false</td>
157+
</tr></tbody>
158+
</table>
159+
160+
161+
### Eviction.status.conditions[index]
162+
<sup><sup>[↩ Parent](#evictionstatus)</sup></sup>
163+
164+
165+
166+
Condition contains details for one aspect of the current state of this API Resource.
167+
168+
<table>
169+
<thead>
170+
<tr>
171+
<th>Name</th>
172+
<th>Type</th>
173+
<th>Description</th>
174+
<th>Required</th>
175+
</tr>
176+
</thead>
177+
<tbody><tr>
178+
<td><b>lastTransitionTime</b></td>
179+
<td>string</td>
180+
<td>
181+
lastTransitionTime is the last time the condition transitioned from one status to another.
182+
This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.<br/>
183+
<br/>
184+
<i>Format</i>: date-time<br/>
185+
</td>
186+
<td>true</td>
187+
</tr><tr>
188+
<td><b>message</b></td>
189+
<td>string</td>
190+
<td>
191+
message is a human readable message indicating details about the transition.
192+
This may be an empty string.<br/>
193+
</td>
194+
<td>true</td>
195+
</tr><tr>
196+
<td><b>reason</b></td>
197+
<td>string</td>
198+
<td>
199+
reason contains a programmatic identifier indicating the reason for the condition's last transition.
200+
Producers of specific condition types may define expected values and meanings for this field,
201+
and whether the values are considered a guaranteed API.
202+
The value should be a CamelCase string.
203+
This field may not be empty.<br/>
204+
</td>
205+
<td>true</td>
206+
</tr><tr>
207+
<td><b>status</b></td>
208+
<td>enum</td>
209+
<td>
210+
status of the condition, one of True, False, Unknown.<br/>
211+
<br/>
212+
<i>Enum</i>: True, False, Unknown<br/>
213+
</td>
214+
<td>true</td>
215+
</tr><tr>
216+
<td><b>type</b></td>
217+
<td>string</td>
218+
<td>
219+
type of condition in CamelCase or in foo.example.com/CamelCase.<br/>
220+
</td>
221+
<td>true</td>
222+
</tr><tr>
223+
<td><b>observedGeneration</b></td>
224+
<td>integer</td>
225+
<td>
226+
observedGeneration represents the .metadata.generation that the condition was set based upon.
227+
For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
228+
with respect to the current state of the instance.<br/>
229+
<br/>
230+
<i>Format</i>: int64<br/>
231+
<i>Minimum</i>: 0<br/>
232+
</td>
233+
<td>false</td>
234+
</tr></tbody>
235+
</table>

0 commit comments

Comments
 (0)