docs: Add generated API references to our book (#272)

If crds.dev goes away we have the APIs being generated in our book as well.
oracle · May 25, 2023 · 18012bf · 18012bf
1 parent 5b12f2c
commit 18012bf
Show file tree

Hide file tree

Showing 13 changed files with 44 additions and 4 deletions.
diff --git a/api/v1beta1/doc.go b/api/v1beta1/doc.go
@@ -15,5 +15,5 @@
 */
 
 // +k8s:conversion-gen=github.com/oracle/cluster-api-provider-oci/api/v1beta2
-
+// +groupName=infrastructure.cluster.x-k8s.io
 package v1beta1
diff --git a/api/v1beta1/groupversion_info.go b/api/v1beta1/groupversion_info.go
@@ -16,7 +16,6 @@ limitations under the License.
 
 // Package v1beta1 contains API Schema definitions for the infrastructure v1beta1 API group
 // +kubebuilder:object:generate=true
-// +groupName=infrastructure.cluster.x-k8s.io
 package v1beta1
 
 import (

diff --git a/api/v1beta2/doc.go b/api/v1beta2/doc.go
@@ -14,4 +14,5 @@
  limitations under the License.
 */
 
+// +groupName=infrastructure.cluster.x-k8s.io
 package v1beta2
diff --git a/api/v1beta2/groupversion_info.go b/api/v1beta2/groupversion_info.go
@@ -16,7 +16,6 @@ limitations under the License.
 
 // Package v1beta2 contains API Schema definitions for the infrastructure v1beta2 API group
 // +kubebuilder:object:generate=true
-// +groupName=infrastructure.cluster.x-k8s.io
 package v1beta2
 
 import (

diff --git a/docs/build.sh b/docs/build.sh
@@ -22,6 +22,7 @@ os=$(go env GOOS)
 arch=$(go env GOARCH)
 
 MDBOOK_VERSION="0.4.21"
+genCRDAPIReferenceDocsVersion="11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a"
 
 # translate arch to rust's conventions (if we can)
 if [[ ${arch} == "amd64" ]]; then
@@ -65,5 +66,22 @@ curl -sL -o /tmp/mdbook.${ext} "https://github.com/rust-lang/mdBook/releases/dow
 ${cmd} /tmp/mdbook.${ext}
 chmod +x /tmp/mdbook
 
+
+# Generate API docs
+genCRDAPIReferenceDocsPath="/tmp/gen-crd-api-reference-docs-${genCRDAPIReferenceDocsVersion}"
+genCRDAPIReferenceDocs="${genCRDAPIReferenceDocsPath}/gen-crd-api-reference-docs"
+(
+  cd /tmp
+  curl --retry 3 -sL -o gen-crd-api-reference-docs.zip "https://github.com/ahmetb/gen-crd-api-reference-docs/archive/${genCRDAPIReferenceDocsVersion}.zip"
+  unzip -o gen-crd-api-reference-docs.zip
+  cd "gen-crd-api-reference-docs-${genCRDAPIReferenceDocsVersion}"
+  go build .
+)
+
+${genCRDAPIReferenceDocs} -config "${genCRDAPIReferenceDocsPath}/example-config.json" -template-dir "${genCRDAPIReferenceDocsPath}/template" -api-dir ./api/v1beta1 -out-file ./docs/src/reference/v1beta1-api-raw.html
+${genCRDAPIReferenceDocs} -config "${genCRDAPIReferenceDocsPath}/example-config.json" -template-dir "${genCRDAPIReferenceDocsPath}/template" -api-dir ./api/v1beta2 -out-file ./docs/src/reference/v1beta2-api-raw.html
+${genCRDAPIReferenceDocs} -config "${genCRDAPIReferenceDocsPath}/example-config.json" -template-dir "${genCRDAPIReferenceDocsPath}/template" -api-dir ./exp/api/v1beta1 -out-file ./docs/src/reference/v1beta1-exp-api-raw.html
+${genCRDAPIReferenceDocs} -config "${genCRDAPIReferenceDocsPath}/example-config.json" -template-dir "${genCRDAPIReferenceDocsPath}/template" -api-dir ./exp/api/v1beta2 -out-file ./docs/src/reference/v1beta2-exp-api-raw.html
+
 # Finally build the book.
 (cd docs && /tmp/mdbook build)
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -41,4 +41,8 @@
   - [Networking customizations](./managed/networking.md)
 - [Reference](./reference/reference.md)
   - [API Reference](./reference/api-reference.md)
+    - [v1beta2 API](./reference/v1beta2-api.md)
+    - [v1beta2 exp API](./reference/v1beta2-exp-api.md)
+    - [v1beta1 API](./reference/v1beta1-api.md)
+    - [v1beta1 exp API](./reference/v1beta1-exp-api.md)
   - [Glossary](./reference/glossary.md)
diff --git a/docs/src/reference/api-reference.md b/docs/src/reference/api-reference.md
@@ -1,4 +1,9 @@
 # API Reference
 
-Cluster API Provider for OCI API Reference is published [here](https://doc.crds.dev/github.com/oracle/cluster-api-provider-oci).
+Versioned Cluster API Provider for OCI API references is published [here](https://doc.crds.dev/github.com/oracle/cluster-api-provider-oci).
 
+You can also find all the APIs in our book. The links are below:
+- [v1beta2](./reference/v1beta2-api.md)
+- [exp v1beta2](./reference/v1beta2-exp-api.md)
+- [v1beta1](./reference/v1beta1-api.md)
+- [exp v1beta1](./reference/v1beta1-exp-api.md)
diff --git a/docs/src/reference/v1beta1-api.md b/docs/src/reference/v1beta1-api.md
@@ -0,0 +1,3 @@
+# v1beta1 API
+
+{{ #include v1beta1-api-raw.html }}
diff --git a/docs/src/reference/v1beta1-exp-api.md b/docs/src/reference/v1beta1-exp-api.md
@@ -0,0 +1,3 @@
+# v1beta1 exp API
+
+{{ #include v1beta1-exp-api-raw.html }}
diff --git a/docs/src/reference/v1beta2-api.md b/docs/src/reference/v1beta2-api.md
@@ -0,0 +1,3 @@
+# v1beta2 API
+
+{{ #include v1beta2-api-raw.html }}
diff --git a/docs/src/reference/v1beta2-exp-api.md b/docs/src/reference/v1beta2-exp-api.md
@@ -0,0 +1,3 @@
+# v1beta2 exp API
+
+{{ #include v1beta2-exp-api-raw.html }}
diff --git a/exp/api/v1beta1/doc.go b/exp/api/v1beta1/doc.go
@@ -15,5 +15,6 @@ limitations under the License.
 */
 
 // +k8s:conversion-gen=github.com/oracle/cluster-api-provider-oci/exp/api/v1beta2
+// +groupName=infrastructure.cluster.x-k8s.io
 
 package v1beta1
diff --git a/exp/api/v1beta2/doc.go b/exp/api/v1beta2/doc.go
@@ -14,4 +14,5 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// +groupName=infrastructure.cluster.x-k8s.io
 package v1beta2