docs: Add generated API references to our book

[joekr]

What this PR does / why we need it:
If crds.dev goes away we have the APIs being generated in our book as well.

Which issue(s) this PR fixes (optional, in fixes #<issue number>(, fixes #<issue_number>, ...) format, will close the issue(s) when PR gets merged):
Fixes #269

[joekr]

I'm still not 100% sure if we want to commit the raw generated files or ignore them. I'm leaning towards committing them but I want to test how the book generation works in github actions.

Quick example of the generated docs

[shyamradhakrishnan]

Looks good, can you please paste output of unit test and build.sh before merging.

[joekr]

Unit Tests

?       github.com/oracle/cluster-api-provider-oci      [no test files]
ok      github.com/oracle/cluster-api-provider-oci/api/v1beta1  22.980s coverage: 24.1% of statements
ok      github.com/oracle/cluster-api-provider-oci/api/v1beta2  0.641s  coverage: 15.8% of statements
?       github.com/oracle/cluster-api-provider-oci/cloud/config [no test files]
?       github.com/oracle/cluster-api-provider-oci/cloud/metrics        [no test files]
ok      github.com/oracle/cluster-api-provider-oci/cloud/ociutil        0.282s  coverage: 19.6% of statements
ok      github.com/oracle/cluster-api-provider-oci/cloud/scope  239.359s        coverage: 76.3% of statements
?       github.com/oracle/cluster-api-provider-oci/cloud/scope/mocks    [no test files]
?       github.com/oracle/cluster-api-provider-oci/cloud/services/base  [no test files]
?       github.com/oracle/cluster-api-provider-oci/cloud/services/base/mock_base        [no test files]
?       github.com/oracle/cluster-api-provider-oci/cloud/services/compute       [no test files]
?       github.com/oracle/cluster-api-provider-oci/cloud/services/compute/mock_compute  [no test files]
?       github.com/oracle/cluster-api-provider-oci/cloud/services/computemanagement     [no test files]
?       github.com/oracle/cluster-api-provider-oci/cloud/services/computemanagement/mock_computemanagement      [no test files]
?       github.com/oracle/cluster-api-provider-oci/cloud/services/containerengine       [no test files]
?       github.com/oracle/cluster-api-provider-oci/cloud/services/containerengine/mock_containerengine  [no test files]
?       github.com/oracle/cluster-api-provider-oci/cloud/services/identity      [no test files]
?       github.com/oracle/cluster-api-provider-oci/cloud/services/identity/mock_identity        [no test files]
?       github.com/oracle/cluster-api-provider-oci/cloud/services/loadbalancer  [no test files]
?       github.com/oracle/cluster-api-provider-oci/cloud/services/loadbalancer/mock_lb  [no test files]
?       github.com/oracle/cluster-api-provider-oci/cloud/services/networkloadbalancer   [no test files]
?       github.com/oracle/cluster-api-provider-oci/cloud/services/networkloadbalancer/mock_nlb  [no test files]
?       github.com/oracle/cluster-api-provider-oci/cloud/services/vcn   [no test files]
?       github.com/oracle/cluster-api-provider-oci/cloud/services/vcn/mock_vcn  [no test files]
ok      github.com/oracle/cluster-api-provider-oci/cloud/util   0.570s  coverage: 76.1% of statements
ok      github.com/oracle/cluster-api-provider-oci/controllers  27.345s coverage: 67.5% of statements
ok      github.com/oracle/cluster-api-provider-oci/exp/api/v1beta1      17.351s coverage: 21.8% of statements
ok      github.com/oracle/cluster-api-provider-oci/exp/api/v1beta2      0.850s  coverage: 10.9% of statements
ok      github.com/oracle/cluster-api-provider-oci/exp/controllers      2.264s  coverage: 56.3% of statements
?       github.com/oracle/cluster-api-provider-oci/feature      [no test files]
?       github.com/oracle/cluster-api-provider-oci/version      [no test files]
go tool cover -func=coverage.out -o coverage.txt
go tool cover -html=coverage.out -o coverage.html

make build-book output

This calls build.sh for the book

docs/build.sh
downloading mdBook-v0.4.21-x86_64-apple-darwin.tar.gz
+ curl -sL -o /tmp/mdbook.tar.gz https://github.com/rust-lang/mdBook/releases/download/v0.4.21/mdBook-v0.4.21-x86_64-apple-darwin.tar.gz
+ tar -C /tmp -xzvf /tmp/mdbook.tar.gz
x mdbook
+ chmod +x /tmp/mdbook
+ genCRDAPIReferenceDocsPath=/tmp/gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a
+ genCRDAPIReferenceDocs=/tmp/gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/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/11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a.zip
+ unzip -o gen-crd-api-reference-docs.zip
Archive:  gen-crd-api-reference-docs.zip
11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a
  inflating: gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/.gitignore  
  inflating: gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/.goreleaser.yml  
  inflating: gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/.travis.yml  
  inflating: gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/LICENSE  
  inflating: gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/README.md  
  inflating: gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/example-config.json  
  inflating: gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/go.mod  
  inflating: gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/go.sum  
  inflating: gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/main.go  
  inflating: gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/template/members.tpl  
  inflating: gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/template/pkg.tpl  
  inflating: gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/template/placeholder.go  
  inflating: gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/template/type.tpl  
+ cd gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a
+ go build .
+ /tmp/gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/gen-crd-api-reference-docs -config /tmp/gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/example-config.json -template-dir /tmp/gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/template -api-dir ./api/v1beta1 -out-file ./docs/src/reference/v1beta1-api-raw.html
I0525 12:10:14.597726   77864 main.go:132] parsing go packages in directory ./api/v1beta1
I0525 12:10:59.223199   77864 main.go:234] using package=./api/v1beta1
W0525 12:10:59.253551   77864 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:10:59.254171   77864 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.Conditions
W0525 12:10:59.254456   77864 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:10:59.254522   77864 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.FailureDomains
W0525 12:10:59.254613   77864 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.Conditions
W0525 12:10:59.255030   77864 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:10:59.256435   77864 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.MachineAddress
W0525 12:10:59.256488   77864 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/errors.MachineStatusError
W0525 12:10:59.256584   77864 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.Conditions
I0525 12:10:59.263568   77864 main.go:170] written to ./docs/src/reference/v1beta1-api-raw.html
+ /tmp/gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/gen-crd-api-reference-docs -config /tmp/gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/example-config.json -template-dir /tmp/gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/template -api-dir ./api/v1beta2 -out-file ./docs/src/reference/v1beta2-api-raw.html
I0525 12:10:59.288590   78350 main.go:132] parsing go packages in directory ./api/v1beta2
I0525 12:11:32.889103   78350 main.go:234] using package=./api/v1beta2
W0525 12:11:32.927564   78350 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:11:32.928176   78350 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.Conditions
W0525 12:11:32.928440   78350 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:11:32.928548   78350 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.FailureDomains
W0525 12:11:32.928606   78350 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.Conditions
W0525 12:11:32.929240   78350 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:11:32.930560   78350 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.MachineAddress
W0525 12:11:32.930625   78350 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/errors.MachineStatusError
W0525 12:11:32.930771   78350 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.Conditions
I0525 12:11:32.937899   78350 main.go:170] written to ./docs/src/reference/v1beta2-api-raw.html
+ /tmp/gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/gen-crd-api-reference-docs -config /tmp/gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/example-config.json -template-dir /tmp/gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/template -api-dir ./exp/api/v1beta1 -out-file ./docs/src/reference/v1beta1-exp-api-raw.html
I0525 12:11:32.970335   78811 main.go:132] parsing go packages in directory ./exp/api/v1beta1
I0525 12:12:03.363079   78811 main.go:234] using package=./exp/api/v1beta1
W0525 12:12:03.390195   78811 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta1.NetworkDetails
W0525 12:12:03.390259   78811 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta1.PlatformConfig
W0525 12:12:03.390310   78811 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta1.LaunchInstanceAgentConfig
W0525 12:12:03.390357   78811 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta1.PreemptibleInstanceConfig
W0525 12:12:03.390411   78811 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta1.LaunchInstanceAvailabilityConfig
W0525 12:12:03.390492   78811 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta1.LaunchOptions
W0525 12:12:03.390543   78811 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta1.InstanceOptions
W0525 12:12:03.392110   78811 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.Conditions
W0525 12:12:03.396077   78811 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/errors.MachineStatusError
W0525 12:12:03.396636   78811 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta1.NetworkSpec
W0525 12:12:03.396789   78811 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:12:03.397032   78811 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta1.NetworkSpec
W0525 12:12:03.397171   78811 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:12:03.397246   78811 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.FailureDomains
W0525 12:12:03.397297   78811 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta1.OCIAvailabilityDomain
W0525 12:12:03.397363   78811 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.Conditions
W0525 12:12:03.397796   78811 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta1.NetworkSpec
W0525 12:12:03.397930   78811 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:12:03.398301   78811 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:12:03.398566   78811 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:12:03.398672   78811 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.Conditions
W0525 12:12:03.399067   78811 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:12:03.399899   78811 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.Conditions
W0525 12:12:03.399969   78811 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/errors.MachineStatusError
I0525 12:12:03.403807   78811 main.go:170] written to ./docs/src/reference/v1beta1-exp-api-raw.html
+ /tmp/gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/gen-crd-api-reference-docs -config /tmp/gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/example-config.json -template-dir /tmp/gen-crd-api-reference-docs-11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a/template -api-dir ./exp/api/v1beta2 -out-file ./docs/src/reference/v1beta2-exp-api-raw.html
I0525 12:12:03.437625   79317 main.go:132] parsing go packages in directory ./exp/api/v1beta2
I0525 12:12:35.131977   79317 main.go:234] using package=./exp/api/v1beta2
W0525 12:12:35.166760   79317 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta2.NetworkDetails
W0525 12:12:35.166941   79317 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta2.PlatformConfig
W0525 12:12:35.167072   79317 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta2.LaunchInstanceAgentConfig
W0525 12:12:35.167194   79317 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta2.PreemptibleInstanceConfig
W0525 12:12:35.167316   79317 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta2.LaunchInstanceAvailabilityConfig
W0525 12:12:35.167531   79317 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta2.LaunchOptions
W0525 12:12:35.167646   79317 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta2.InstanceOptions
W0525 12:12:35.170611   79317 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.Conditions
W0525 12:12:35.170684   79317 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/errors.MachineStatusError
W0525 12:12:35.171182   79317 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta2.NetworkSpec
W0525 12:12:35.171407   79317 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:12:35.171470   79317 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta2.OCIAvailabilityDomain
W0525 12:12:35.171539   79317 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta2.ClientOverrides
W0525 12:12:35.171901   79317 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta2.NetworkSpec
W0525 12:12:35.172105   79317 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:12:35.172180   79317 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta2.OCIAvailabilityDomain
W0525 12:12:35.172235   79317 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta2.ClientOverrides
W0525 12:12:35.172328   79317 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.FailureDomains
W0525 12:12:35.172417   79317 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.Conditions
W0525 12:12:35.172927   79317 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta2.NetworkSpec
W0525 12:12:35.173091   79317 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:12:35.173164   79317 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta2.OCIAvailabilityDomain
W0525 12:12:35.173218   79317 main.go:445] not found external link source for type github.com/oracle/cluster-api-provider-oci/api/v1beta2.ClientOverrides
W0525 12:12:35.173886   79317 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:12:35.174261   79317 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:12:35.174433   79317 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.Conditions
W0525 12:12:35.174899   79317 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.APIEndpoint
W0525 12:12:35.176121   79317 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/api/v1beta1.Conditions
W0525 12:12:35.176213   79317 main.go:445] not found external link source for type sigs.k8s.io/cluster-api/errors.MachineStatusError
I0525 12:12:35.180321   79317 main.go:170] written to ./docs/src/reference/v1beta2-exp-api-raw.html
+ cd docs
+ /tmp/mdbook build
2023-05-25 12:12:37 [INFO] (mdbook::book): Book building has started
2023-05-25 12:12:37 [INFO] (mdbook::book): Running the html backend