Skip to content

🌱 Auto-generate API documentation from CRDs #2605

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
MahnoorAsghar wants to merge 1 commit into
base: main
Choose a base branch
from
Open

🌱 Auto-generate API documentation from CRDs #2605

MahnoorAsghar wants to merge 1 commit into from

Conversation

@MahnoorAsghar
Copy link
Contributor

@MahnoorAsghar MahnoorAsghar commented Aug 8, 2025 •
edited
Loading

Auto-generate API documentation from CRDs

Assisted-by: Claude
Fixes #2509

@metal3-io-bot
Copy link
Contributor

metal3-io-bot commented Aug 8, 2025

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign lentzi90 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@metal3-io-bot metal3-io-bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Aug 8, 2025
@tuminoid
Copy link
Member

tuminoid commented Aug 8, 2025

This is copy from IRSO's api doc generator right?

@MahnoorAsghar
Copy link
Contributor Author

MahnoorAsghar commented Aug 8, 2025

@tuminoid

This is copy from IRSO's api doc generator right?

Yes, it is

@MahnoorAsghar MahnoorAsghar force-pushed the crd-doc branch 2 times, most recently from 2a53530 to fbed203 Compare August 8, 2025 15:27
@MahnoorAsghar
Copy link
Contributor Author

MahnoorAsghar commented Sep 23, 2025

/retest-required

@MahnoorAsghar MahnoorAsghar mentioned this pull request Sep 24, 2025
Merged
@MahnoorAsghar
Copy link
Contributor Author

MahnoorAsghar commented Sep 24, 2025

/retest-required

tuminoid
tuminoid reviewed Sep 25, 2025
View reviewed changes
Copy link
Member

@tuminoid tuminoid left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The difference between this BMO PR and IRSO here is that IRSO runs the "make manifests" as part of build Github workflow (in a VM), while BMO runs make generate as a Prow job (in a container).

The correct way for BMO would be to have it in a separate Prow job, which runs the crdoc container in Prow.

hack/gen-api-doc.sh Outdated
"${CONTAINER_RUNTIME}" run --rm -v "${PWD}":/src:ro,z \
ghcr.io/fybrik/crdoc:"${CRDOC_VERSION}" \
--resources /src/config/base/crds/bases/ --output /dev/stdout \
> docs/api.md No newline at end of file
Copy link
Member

@tuminoid tuminoid Sep 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

missing eol

@MahnoorAsghar MahnoorAsghar changed the title 🌱 Auto-generate API documentation from CRDs WIP 🌱 Auto-generate API documentation from CRDs Sep 25, 2025
@metal3-io-bot metal3-io-bot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Sep 25, 2025
@MahnoorAsghar MahnoorAsghar mentioned this pull request Sep 26, 2025
Open
@tuminoid tuminoid mentioned this pull request Nov 24, 2025
Closed
@MahnoorAsghar
Copy link
Contributor Author

MahnoorAsghar commented Dec 12, 2025

I dont remember how docs/api-overview.md came from, it must be output from the script, but executing it right now does not create it.

@MahnoorAsghar MahnoorAsghar force-pushed the crd-doc branch 3 times, most recently from 1d6aabf to 861dc18 Compare December 12, 2025 22:42
@MahnoorAsghar
Copy link
Contributor Author

MahnoorAsghar commented Dec 12, 2025 •
edited
Loading

For the check-links-pr job, https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#objectmeta-v1-meta is the correct url, but the crdoc container is generating v1.20 links which are indeed broken

This could be because the latest crdoc container version is 3 years old. There are 2 tagged releases on the repo after that, but no associated container images. See fybrik/crdoc#322

@MahnoorAsghar
Copy link
Contributor Author

MahnoorAsghar commented Dec 12, 2025

I could add the exclude-path option to https://github.com/metal3-io/baremetal-operator/blob/main/.github/workflows/pr-link-check.yml and https://github.com/metal3-io/project-infra/blob/1f19a2b8b926ab9bec62b1b8099cecf492d2125d/.github/workflows/pr-link-check.yml#L64
to ignore the path failures :D

@MahnoorAsghar MahnoorAsghar changed the title WIP 🌱 Auto-generate API documentation from CRDs 🌱 Auto-generate API documentation from CRDs Dec 12, 2025
@metal3-io-bot metal3-io-bot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Dec 12, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@tuminoid tuminoid tuminoid left review comments

@iurygregory iurygregory Awaiting requested review from iurygregory

@kashifest kashifest Awaiting requested review from kashifest

Assignees

No one assigned

Labels

size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Generate local API documentation from CRDs

3 participants

@MahnoorAsghar @metal3-io-bot @tuminoid