📖 Add API reference documentation generation #1702

alexandrevilain · 2023-10-02T12:47:19Z

What this PR does / why we need it:

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 #1694

Special notes for your reviewer:

Please confirm that if this PR changes any image versions, then that's the sole change this PR makes.

TODOs:

squashed commits
if necessary:
- includes documentation
- adds unit tests

/hold

netlify · 2023-10-02T12:47:24Z

✅ Deploy Preview for kubernetes-sigs-cluster-api-openstack ready!

Name	Link
🔨 Latest commit	`af5545c`
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-sigs-cluster-api-openstack/deploys/65df61829516790008d807be
😎 Deploy Preview	https://deploy-preview-1702--kubernetes-sigs-cluster-api-openstack.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

k8s-ci-robot · 2023-10-02T12:47:28Z

Hi @alexandrevilain. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

wwentland · 2023-10-02T17:30:34Z

/ok-to-test

alexandrevilain · 2023-10-02T18:11:16Z

/retest

jichenjc · 2023-10-03T10:38:40Z

Thanks for the PR
where can we check the output of the newly added PR? e.g some test doc etc?

alexandrevilain · 2023-10-03T12:01:19Z

Thanks for the PR where can we check the output of the newly added PR? e.g some test doc etc?

You can check it here: https://deploy-preview-1702--kubernetes-sigs-cluster-api-openstack.netlify.app/api/v1alpha7/api

mdbooth · 2023-10-04T11:44:37Z

Thank you! I will try to review this properly asap if nobody gets to it before me.

mdbooth

This looks fantastic. Couple of questions inline, but I think we can merge this soon.

Thank you!

mdbooth · 2023-10-04T11:50:32Z

api/v1alpha6/openstackcluster_types.go

+// +genclient
+// +genclient:Namespaced


Do you know why these are required?

Yes, because complete support for kubebuilder v2 is still missing in the tool ahmetb/gen-crd-api-reference-docs#15

mdbooth · 2023-10-04T11:50:58Z

docs/book/gen-crd-api-reference-docs/template/members.tpl

Did you hand-craft these templates, or were they copied from somewhere?

It's a copy-past from https://github.com/ahmetb/gen-crd-api-reference-docs/tree/master/template

mdbooth · 2023-10-04T11:54:12Z

docs/book/src/api/index.md

Don't suppose there's any way to generate this? No worries if not, it can be hand-crafted.

No idea, maybe we can create a tool to generate this after generating apis doc in the makefile

wwentland

Thank you, this is indeed very nice!

Alternative approaches

I just had a look at gen-crd-api-reference-docs and noticed the following comment:

Nowadays, I don't have a lot of time to maintain this tool. So consider using one of the above in case this repo does not work for you.
If you're an open source project, consider exposing your CRD API Reference via https://doc.crds.dev/ without much effort.

Which reminds me of https://xkcd.com/2347/ and I have, in fact, used the CRD API references on https://doc.crds.dev/ countless times as a user myself:

https://doc.crds.dev/github.com/kubernetes-sigs/cluster-api-provider-openstack@v0.8.0

Those are always up-to-date and you can also browse earlier versions easily. Including a link to that website, might be a viable alternative to generating the reference documentation ourselves.

That being said, I do like the outcome, generating the reference documentation ourselves means we are not depending on an external service, and the tool appears to be well adopted within the community.

Licensing

Is there anything we need to do when copy & pasting templates from gen-crd-api-reference-docs/tree/master/template from a licensing perspective?

I see that the project does not include its own copyright notice, which makes it a bit harder to comply with the license requirement to retain the original statement.

wwentland · 2023-10-07T05:10:08Z

Makefile

+generate-api-docs: $(GEN_CRD_API_REFERENCE_DOCS) ## Generate api documentation
+	$(GEN_CRD_API_REFERENCE_DOCS) \
+		-api-dir=./api/v1alpha7 \
+		-config=./docs/book/gen-crd-api-reference-docs/config.json \


This files seems to be missing and I see the following error in the test results:

-template-dir=./docs/book/gen-crd-api-reference-docs/template \ -out-file=./docs/book/src/api/v1alpha6/api.md F1005 08:16:40.577071 16819 main.go:123] failed to open config file: open ./docs/book/gen-crd-api-reference-docs/config.json: no such file or directory make[1]: *** [Makefile:288: generate-api-docs] Error 255 make[1]: Leaving directory '/home/prow/go/src/sigs.k8s.io/cluster-api-provider-openstack' make: *** [Makefile:255: generate] Error 2

Do we have to provide it or would the tool fall back to reasonable defaults if we don't?

Oh! I understand why CI was failing ... config.json is gitignored ! Fixing this !

I also happened to discover we're ignoring '*.json' just last week. We should get rid of that rule; it's weird.

jichenjc · 2023-10-09T06:09:21Z

/test pull-cluster-api-provider-openstack-test

alexandrevilain · 2023-10-09T08:30:39Z

/retest

mdbooth · 2023-10-13T16:08:07Z

Not sure what that test failure is about. I really want to get this merged, so if I get some time I'll investigate myself if nobody beats me to it.

alexandrevilain · 2023-10-13T16:32:14Z

Not sure what that test failure is about. I really want to get this merged, so if I get some time I'll investigate myself if nobody beats me to it.

No idea why test are failing ... I tried rebase in case of failing CI on the main branch. I'll try to investigate on Monday too.

alexandrevilain · 2023-10-16T07:50:35Z

Ok it was only a bad rebase on my side.

/remove-hold

alexandrevilain · 2023-11-02T15:09:28Z

I had to rebase to make the CI pass.

alexandrevilain · 2023-12-15T13:11:57Z

Will try to do the rebase today.

EmilienM · 2024-02-21T17:12:47Z

Hello, could we add v1alpha8 please and rebase? Thanks a lot :)

alexandrevilain · 2024-02-22T09:39:31Z

Hello @EmilienM !

Done, waiting for CI to pass.

alexandrevilain · 2024-02-22T09:42:20Z

You can check deploy preview here: https://deploy-preview-1702--kubernetes-sigs-cluster-api-openstack.netlify.app/api/v1alpha8/api

EmilienM · 2024-02-22T14:34:50Z

      unable to install CRDs onto control plane: unable to create CRD instances: unable to create CRD "openstackclustertemplates.infrastructure.cluster.x-k8s.io": CustomResourceDefinition.apiextensions.k8s.io "openstackclustertemplates.infrastructure.cluster.x-k8s.io" is invalid: [spec.versions: Invalid value: []apiextensions.CustomResourceDefinitionVersion{apiextensions.CustomResourceDefinitionVersion{Name:"v1alpha5", Served:false, Storage:false, Deprecated:true, DeprecationWarning:(*string)(0xc0038adfd0), Schema:(*apiextensions.CustomResourceValidation)(0xc0008d4a58), Subresources:(*apiextensions.CustomResourceSubresources)(nil), AdditionalPrinterColumns:[]apiextensions.CustomResourceColumnDefinition(nil)}, apiextensions.CustomResourceDefinitionVersion{Name:"v1alpha6", Served:true, Storage:false, Deprecated:false, DeprecationWarning:(*string)(nil), Schema:(*apiextensions.CustomResourceValidation)(0xc0008d4b98), Subresources:(*apiextensions.CustomResourceSubresources)(nil), AdditionalPrinterColumns:[]apiextensions.CustomResourceColumnDefinition(nil)}, apiextensions.CustomResourceDefinitionVersion{Name:"v1alpha7", Served:true, Storage:true, Deprecated:false, DeprecationWarning:(*string)(nil), Schema:(*apiextensions.CustomResourceValidation)(0xc0008d4bb0), Subresources:(*apiextensions.CustomResourceSubresources)(nil), AdditionalPrinterColumns:[]apiextensions.CustomResourceColumnDefinition(nil)}, apiextensions.CustomResourceDefinitionVersion{Name:"v1alpha8", Served:true, Storage:true, Deprecated:false, DeprecationWarning:(*string)(nil), Schema:(*apiextensions.CustomResourceValidation)(0xc0008d4c50), Subresources:(*apiextensions.CustomResourceSubresources)(nil), AdditionalPrinterColumns:[]apiextensions.CustomResourceColumnDefinition(nil)}}: must have exactly one version marked as storage version, status.storedVersions: Invalid value: []string{"v1alpha7"}: must have the storage version v1alpha8]

I'm not sure why we have this error, let us know if you need help on this one.

@mdbooth I would love to get this one at some point, not blocking anything but I'm glad @alexandrevilain can still work on it.
Thanks

alexandrevilain · 2024-02-22T14:48:38Z

@EmilienM I rebased and re-run make generate. Will see if it works

api/v1alpha8/doc.go

api/v1alpha7/openstackmachinetemplate_types.go

api/v1alpha6/openstackclustertemplate_types.go

Signed-off-by: alexandre.vilain <alexandre.vilain@corp.ovh.com>

alexandrevilain · 2024-02-28T19:14:00Z

@EmilienM CI is now green 👍

EmilienM · 2024-02-28T20:14:41Z

/lgtm

k8s-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Oct 2, 2023

k8s-ci-robot requested review from jichenjc and mdbooth October 2, 2023 12:47

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Oct 2, 2023

k8s-ci-robot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Oct 2, 2023

k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Oct 2, 2023

mdbooth reviewed Oct 4, 2023

View reviewed changes

alexandrevilain force-pushed the docs/add-api-reference branch 2 times, most recently from 0b4f229 to b64855a Compare October 5, 2023 08:11

wwentland reviewed Oct 7, 2023

View reviewed changes

alexandrevilain force-pushed the docs/add-api-reference branch 2 times, most recently from 40b025d to 694416b Compare October 9, 2023 08:09

mdbooth mentioned this pull request Oct 9, 2023

✨ Generate reference documentation automatically from godocs in the API #1703

Closed

alexandrevilain force-pushed the docs/add-api-reference branch 2 times, most recently from 6c0f3b1 to 862ee63 Compare October 13, 2023 07:31

alexandrevilain force-pushed the docs/add-api-reference branch from 862ee63 to b5cf1a5 Compare October 16, 2023 07:32

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Dec 15, 2023

alexandrevilain force-pushed the docs/add-api-reference branch from b6cac65 to 291b2ac Compare February 22, 2024 09:11

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Feb 22, 2024

alexandrevilain force-pushed the docs/add-api-reference branch from 291b2ac to b550d0e Compare February 22, 2024 09:39

alexandrevilain force-pushed the docs/add-api-reference branch 2 times, most recently from 3066a8c to e80879c Compare February 22, 2024 10:29

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Feb 22, 2024

alexandrevilain force-pushed the docs/add-api-reference branch from e80879c to 727e193 Compare February 22, 2024 14:48

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Feb 22, 2024

EmilienM reviewed Feb 22, 2024

View reviewed changes

api/v1alpha8/doc.go Outdated Show resolved Hide resolved

EmilienM reviewed Feb 22, 2024

View reviewed changes

api/v1alpha7/openstackmachinetemplate_types.go Outdated Show resolved Hide resolved

EmilienM reviewed Feb 22, 2024

View reviewed changes

api/v1alpha6/openstackclustertemplate_types.go Outdated Show resolved Hide resolved

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Feb 28, 2024

alexandrevilain force-pushed the docs/add-api-reference branch 2 times, most recently from 0fe9409 to 69baa16 Compare February 28, 2024 16:34

Add API reference documentation generation

af5545c

Signed-off-by: alexandre.vilain <alexandre.vilain@corp.ovh.com>

alexandrevilain force-pushed the docs/add-api-reference branch from 69baa16 to af5545c Compare February 28, 2024 16:38

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Feb 28, 2024

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Feb 28, 2024

k8s-ci-robot merged commit 36e94d9 into kubernetes-sigs:main Feb 28, 2024
9 checks passed

alexandrevilain deleted the docs/add-api-reference branch February 29, 2024 08:48

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

📖 Add API reference documentation generation #1702

📖 Add API reference documentation generation #1702

alexandrevilain commented Oct 2, 2023

netlify bot commented Oct 2, 2023 •

edited

k8s-ci-robot commented Oct 2, 2023

wwentland commented Oct 2, 2023

alexandrevilain commented Oct 2, 2023

jichenjc commented Oct 3, 2023

alexandrevilain commented Oct 3, 2023

mdbooth commented Oct 4, 2023

mdbooth left a comment

mdbooth Oct 4, 2023

alexandrevilain Oct 4, 2023

mdbooth Oct 4, 2023

alexandrevilain Oct 4, 2023

mdbooth Oct 4, 2023

alexandrevilain Oct 4, 2023

wwentland left a comment

wwentland Oct 7, 2023

alexandrevilain Oct 9, 2023

mdbooth Oct 9, 2023

jichenjc commented Oct 9, 2023

alexandrevilain commented Oct 9, 2023

mdbooth commented Oct 13, 2023

alexandrevilain commented Oct 13, 2023

alexandrevilain commented Oct 16, 2023

alexandrevilain commented Nov 2, 2023 •

edited

alexandrevilain commented Dec 15, 2023

EmilienM commented Feb 21, 2024

alexandrevilain commented Feb 22, 2024

alexandrevilain commented Feb 22, 2024

EmilienM commented Feb 22, 2024

alexandrevilain commented Feb 22, 2024

alexandrevilain commented Feb 28, 2024

EmilienM commented Feb 28, 2024

📖 Add API reference documentation generation #1702

📖 Add API reference documentation generation #1702

Conversation

alexandrevilain commented Oct 2, 2023

netlify bot commented Oct 2, 2023 • edited

✅ Deploy Preview for kubernetes-sigs-cluster-api-openstack ready!

k8s-ci-robot commented Oct 2, 2023

wwentland commented Oct 2, 2023

alexandrevilain commented Oct 2, 2023

jichenjc commented Oct 3, 2023

alexandrevilain commented Oct 3, 2023

mdbooth commented Oct 4, 2023

mdbooth left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wwentland left a comment

Choose a reason for hiding this comment

Alternative approaches

Licensing

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jichenjc commented Oct 9, 2023

alexandrevilain commented Oct 9, 2023

mdbooth commented Oct 13, 2023

alexandrevilain commented Oct 13, 2023

alexandrevilain commented Oct 16, 2023

alexandrevilain commented Nov 2, 2023 • edited

alexandrevilain commented Dec 15, 2023

EmilienM commented Feb 21, 2024

alexandrevilain commented Feb 22, 2024

alexandrevilain commented Feb 22, 2024

EmilienM commented Feb 22, 2024

alexandrevilain commented Feb 22, 2024

alexandrevilain commented Feb 28, 2024

EmilienM commented Feb 28, 2024

netlify bot commented Oct 2, 2023 •

edited

alexandrevilain commented Nov 2, 2023 •

edited